Skip to main content

Associations API Walkthrough

To create and manage associations you have to follow the Association lifecycle. This document will show examples of Creating, Editing, Deleting and Verifying Associations.

APIs Referenced
Associations Command API
Associations Query API

Create new Association​

Creating a new Association - Use Case​

Create Association Use Case
AS: an API consumer:

     GIVEN: I need to create an association between two entities

     WHEN:  I have gathered all the legal entity data for both parties

     AND: I know the journeyId and association type I want to set

 THEN: I want to call an API to pass in the data and create the association.

Creating a new Association API call​

This Association Command API is used to create a new association between two legal entities. Send a HTTP POST to the URL {{baseURL}}/associationcommand/api/v2/association

Create New Association - JSON POST Body
    "data":
    {
        "sourceId": "0d046bc5-384c-4f4d-aa0b-b32d57bbebc4",
        "targetId": "0a286d53-f1d2-4d28-9719-332f4b04a85b",
        "journeyId": "1ac076a1-442a-444d-8dd3-a10852af3fd2",
        "type": "Member",
        "ownershipPercentage": 20,
        "controlPercentage": 0,
        "properties": {}
    }
}

Understanding the Create Association Request​

This request above contains a number of details which you need to have in advance before you can make the call.

  • "sourceId" This is the Legal Entity Id FROM whom the association is originating.
  • Highlighted in Orange is the Target ID, This is the Legal Entity Id TO whom the association is destined.
  • Highlighted in Yellow is the Journey Id being used to create the associations. Creating and working with associations must be done within the scope of a Journey.
  • Highlighted in Blue is the association type. This is a string value from the reference data list in the configuration. Clients and add any association type requirements to the list but they must be in place before the association can be created.
  • Highlighted in Red are the ownership and control percentages. As above the ownership percentage of the source is being specified as 20% of the target.

Create Association Response​

Once called successfully the API will return a HTTP 202 Accepted response and the data which was sent. In the response it will also contain an Association (Association Id) "id": "6413ef15-c82d-4a1e-966f-a75778676f22". You will need this Id if you are editing, deleting or verifying the association later.

Create Association Response
{
    "data": {
        "id": "6413ef15-c82d-4a1e-966f-a75778676f22",
        "sourceId": "1ccf1c1a-fc01-46fc-95df-4f43f9fbb4c8",
        "targetId": "0a286d53-f1d2-4d28-9719-332f4b04a85b",
        "type": "Member",
        "journeyId": "1ac076a1-442a-444d-8dd3-a10852af3fd2",
        "isVerified": false,
        "ownershipPercentage": 20,
        "controlPercentage": 0,
        "properties": {
            "journeyid": "1ac076a1-442a-444d-8dd3-a10852af3fd2",
            "isverified": "False",
            "ownershippercentage": "20",
            "controlpercentage": "0"
        }
    },
    "messages": null
}

Edit an unverified Association​

Edit an Existing Association - Use Case​

Edit Existing Association Use Case
  AS: an API consumer:

      GIVEN:  I need to update an existing unverified association

      WHEN: I have gathered all the legal entity data for both parties

      AND: I know the Association Id, JourneyId and Association type I want to set

  THEN:  I want to call an API to pass in the data and update the existing association.

Edit an Existing Association API call​

This Association Command API is used to edit an existing unverified association between two legal entities. Send a HTTP PUT to {{baseURL}}/associationcommand/api/v2/association/{associationId} with the below request body.

Update Existing Association - JSON PUT Body
{
    "data": {
        "id": "6413ef15-c82d-4a1e-966f-a75778676f22",
        "sourceId": "0d046bc5-384c-4f4d-aa0b-b32d57bbebc4",
        "targetId": "0a286d53-f1d2-4d28-9719-332f4b04a85b",
        "journeyId": "1ac076a1-442a-444d-8dd3-a10852af3fd2",
        "type": "Member",
        "ownershipPercentage": 20
        >"controlPercentage": 0,
        "properties": {}
    }
}

Understanding the Update Association Request​

This request above contains a number of details which you need to have in advance before you can make the call. Only the

  • The "id" parameter above is the Association Id, This is required in the PUT URL and the JSON Body as above.

Update Association Response​

Once called successfully the API will return a HTTP 202 Accepted response. It will also return the data which was sent.

Delete an unverified Association​

Delete an unverified Association - Use Case​

Delete Association Use Case
  AS an API consumer:

     GIVEN: I need to delete an existing unverified association

     WHEN: I know the Association Id

  THEN: I want to call an API to pass in the data and delete the unverified association.

Delete an Unverified Association API call​

This Association Command API is used to delete an existing unverified association between two legal entities. It is just a HTTP DELETE call and as can be seen below, the Association ID and the Journey ID are passed in the URL itself.

DELETE Association
  {{baseURL}}/associationcommand/api/v2/association/{**Association Id**}/journeyId/{**JourneyId**}

  HTTP DELETE ENDPOINT - Example
  ================================
  {{baseURL}}/associationcommand/api/v2/association/6413ef15-c82d-4a1e-966f-a75778676f22/journeyId/1ac076a1-442a-444d-8dd3-a10852af3fd2

  RETURNS: HTTP 202 Accepted
  ===========================

What if the Association IS verified?​

If the above DELETE call is made against an association which has already been verified, the API will return the below error:

Error Response
  HTTP 400 Bad Request
  =====================
  {
      "data": null,
      "messages": [
          {
              "message": "The association with Id: ebdcd011-f68d-4ee1-b2ac-1dc76d8458a5 is not an unverified association",
              "type": "UnverifiedAssociationDeletion"
          }
      ]
  }

Verify an Association​

Verify an unverified Association - Use Case​

Typically a system task is configured in the end of a journey which is triggered automatically and can be used to verify all related parties which have been created or changed within that Journey. Any changes made to related parties remain inside the scope of a Journey until that Journey is completed. This means that users whi request details of any Legal Entity will not see the changes from a Journey until Verify Related Parties task is completed.

Verify an Association Use Case
  AS:  an API consumer:

     GIVEN: I need verify an existing unverified association

     WHEN: I know the Association Id

 THEN: I want to call an API to pass in the data and delete the unverified association.

Verify all Unverified Associations for a Specific Journey​

This Association Command API is used to verify an existing unverified association between two legal entities. It is a HTTP PUT call and as can be seen below, the Root Entity ID (this is the Entity against whom the Journey is running) along with the Journey Id are passed in.

  HTTP PUT ENDPOINT - Format
  ================================
  {{baseURL}}/associationcommand/api/v2/association/verifyAll/entityId/{**Entity Id**}/journeyId/{**Journey Id**}

  HTTP PUT ENDPOINT - Example
  ================================
  {{baseURL}}associationcommand/api/v2/association/verifyAll/entityId/0a286d53-f1d2-4d28-9719-332f4b04a85b/journeyId/1ac076a1-442a-444d-8dd3-a10852af3fd2

  RETURNS: HTTP 202 Accepted
  ===========================