Managing Partners
Overview
This section focuses on managing partners through our API, which is essential for creating clients, users, and templates. In other words, they are all basically entities of a partner.
Note
If you don't have a parent partner to work with, which cannot be set up as a Partner Supervisor, please contact Bluefin support.
For security reasons, the API is designed to create only Sub-Partners, requiring you to specify a parent partner during the creation process. Similar to User Roles, this ensures that all Sub-Partners are properly associated with an existing parent partner, maintaining a clear and secure organizational structure.
Sub-Partners can have their own users but do not have visibility into the parent Partner or other Sub-Partners, only their own children.
That means if we create a user under the Sub-Partner, the client must be created under that same Sub-Partner and the user role must be Partner Supervisor and lower. If we apply that user - we won't be able to query/get the other Sub-Partners and parents.
Say the user role for another user is the Partner Supervisor and If we tried to use any higher level than the Partner Level, we would get the following error message:
{
"uuid": "83aa2410-59d0-11ef-9fca-7d5196e53ec9",
"errorCode": 7403,
"message": "Permission denied."
}
NOTE: To be exact, other Sub-Partners can be used as parents to create their own Sub-Partners as illustrated in our diagram here: Hierarchy Diagram of Organizations
Ensure that your user role has the necessary permissions to perform these operations. For more information, refer to the Hierarchy of Organizations section.
For requests with additional settings, consult the API Reference.
Creating a Partner
Request
POST /api/v1/partners
{
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Basic Base64(username:password)"
},
"body": {
"name": "subPartnerName",
"isActive": false,
"reference": "7c6377eb4753ad4490302263a6e0a7df",
"parent": {
"id": 792,
"name": "parentPartnerName"
},
"contact": {
"id": 2664,
"firstName": "WATERFORD",
"lastName": "Example",
"email": "[email protected]"
}
}
}
Response
{
"id": 904
}
Getting Partners
This endpoint returns a summarized list of Partners and Sub-Partners. The list of Partners can be filtered by including the partner ID in the request parameters. However as mentioned above, when a Partner User makes the same API call, the results are restricted to their Partner account and Sub-Partners.
For example, with the Partner Supervisor User Role, you have access to view the partner's Sub-Partners, and the children of Sub-Partners. You can identify these relationships in the output by examining the parent field of the Sub-Partners.
Request
GET /api/v1/partners?partner=partnerName
{
"method": "GET",
"headers": {
"Content-Type": "application/json",
"Authorization": "Basic Base64(username:password)"
}
}
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
partner | string/integer | Yes | Filter the list by Partner. The parameter value can be either a Partner ID or Name. |
take | integer | No ( Default: 10) | The number of entries to include in the list. It starts from skip. |
skip | integer | No ( Default: 0 ) | The number of results to skip before listing entries. |
Response
{
"total": 3,
"data": [
{
"id": 792,
"name": "partnerName",
"reference": "c954b4c60a28a337e76cc7ebd7fe9991",
"verificationPhrase": "verificationPhrase",
"version": 6,
"contact": {
"id": 2648
},
"isActive": true,
"partnerId": "c954b4c60a28a337e76cc7ebd7fe9991",
"billingId": "abc123"
},
{
"id": 904,
"name": "subPartnerName",
"reference": "7c6377eb4753ad4490302263a6e0a7df",
"verificationPhrase": null,
"parent": {
"id": 792,
"name": "partnerName"
},
"version": 0,
"contact": {
"id": 2664
},
"isActive": false,
"partnerId": "7c6377eb4753ad4490302263a6e0a7df",
"billingId": null
},
{
"id": 920,
"name": "subPartnerName1",
"reference": "40f4bf910f2fc861e366281f772c3f4a",
"verificationPhrase": null,
"parent": {
"id": 904,
"name": "subPartnerName"
},
"version": 0,
"contact": {
"id": 2664
},
"isActive": false,
"partnerId": "40f4bf910f2fc861e366281f772c3f4a",
"billingId": null
}
]
}
Getting a Partner
In comparison to Getting a list of Partners, getting an individual partner just adds the meta-data created and modified.
Request
GET /api/v1/partners/{id}
{
"method": "GET",
"headers": {
"Content-Type": "application/json",
"Authorization": "Basic Base64(username:password)"
}
}
Response
{
"id": 920,
"name": "subPartnerName1",
"reference": "40f4bf910f2fc861e366281f772c3f4a",
"verificationPhrase": null,
"parent": {
"id": 936,
"name": "subPartnerName"
},
"created": "2024-08-14T00:08:24.000Z",
"modified": "2024-08-14T01:42:34.000Z",
"version": 0,
"contact": {
"id": 2664,
"firstName": "WATERFORD",
"lastName": "Example",
"email": "[email protected]"
},
"isActive": false,
"partnerId": "40f4bf910f2fc861e366281f772c3f4a",
"billingId": null
}
Updating a Partner
Suppose we want to change the parent of a Partner or Sub-Partner to connect it to another group of Sub-Partners. For that, we specify the partner id and name. Along with the partner itself, this would move all its Sub-Partner children to the new parent partner similar to swapping nodes in a Binary Tree.
Request
PATCH /api/v1/partners/{id}
{
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Authorization": "Basic Base64(username:password)"
},
"body": {
"name": "subPartnerName1",
"isActive": false,
"reference": "7c6377eb4753ad4490302263a6e0a7df",
"parent": {
"id": 936,
"name": "newPartnerName"
},
"contact": {
"id": 2664,
"firstName": "WATERFORD",
"lastName": "Example",
"email": "[email protected]"
}
}
}
Response
On success, we receive the id of the updated partner.
{
"id": 920
}
Updated 25 days ago