Assign an existing Collaborator to a Collaborator Group

Suggest Edits

1. Get the Collaborator ID

Before you can add a collaborator to a collaborator group, you must retrieve the collaborator ID. This API endpoint provides an interface for fetching a list of all collaborators for a specific project, aiding users in identifying the collaboratorId required to assign a collaborator to a particular group.

Endpoint

GET https://api.wingspan.app/payments/collaborator

Headers

  • accept: Defines the type of content the client expects. Always set to application/json.
  • content-type: Defines the media type of the request. Always set to application/json.
  • authorization: The authentication token for the API. Prefix with Bearer.

Request

Simply sending a GET request to the above URL with the appropriate header will retrieve a list of collaborators.

Example Request

curl --request GET \
     --url https://api.wingspan.app/payments/collaborator \
     --header 'accept: application/json'

Response

Upon a successful request, the API will return a status code of 200.

Response Body

The response will be an array of objects, with each object representing a collaborator. Each collaborator object will contain:

  • clientId: (String, required) The unique identifier for the client.
  • collaboratorId: (String, required) A unique identifier for the collaborator. This ID is what users are primarily seeking, as it's needed to assign a collaborator to a specific group.
  • createdAt: (String, required) The timestamp indicating when the collaborator was added to the system.

Example Response

[
    {
        "clientId": "c9876543",
        "collaboratorId": "collab123xyz",
        "createdAt": "2023-01-15T12:00:00Z"
    },
    {
        "clientId": "c9876543",
        "collaboratorId": "collab456abc",
        "createdAt": "2023-01-16T14:30:00Z"
    }
]

2. Add a Collaborator to a Collaborator Group

Now that you have the collaboratorId you can assign the collaborator in question to a Collaborator Group. This API endpoint facilitates the addition of a collaborator to a specified collaborator group.

Endpoint

PATCH https://api.wingspan.app/payments/collaborator/{id}/add-group/{groupId}

Path Parameters

  • id: (String, required) The unique identifier for the collaborator you wish to add to a group.
  • groupId: (String, required) The unique identifier of the group to which the collaborator should be added.

Headers

  • accept: Defines the type of content the client expects. Always set to application/json.
  • content-type: Defines the media type of the request. Always set to application/json.
  • authorization: The authentication token for the API. Prefix with Bearer.

Example Request

curl --request PATCH \
     --url https://api.wingspan.app/payments/collaborator/c9876543/add-group/collab456abc \
     --header 'accept: application/json'

Response

Upon a successful operation, the API will return a status code of 200.

Response Body

The response will be an object with the following fields:

  • collaboratorId: (String, required) Unique identifier of the collaborator.
  • createdAt: (String, required) Timestamp indicating when the collaborator was created.
  • memberId: (String, required) Unique identifier of the member associated with the collaborator.
  • status: (String, required) Current status of the collaborator. Possible values include "Active", "Inactive", and "Pending".
  • updatedAt: (String, required) Timestamp of the last update made to the collaborator.
  • userRoles: (Object, required) An object defining roles for users:
    • ownerIds: (Array of strings, required) List of user IDs who have owner rights.
    • viewerIds: (Array of strings, required) List of user IDs who have viewer rights.
  • collaboratorGroupIds: (Array of strings | null) A list of IDs representing the groups the collaborator is a part of.
  • eligibilityRequirements: (Array or null) List of eligibility requirements:
    • clientId: (String, required) Unique identifier for the client.
    • collaboratorGroupId: (String, required) Unique identifier for the collaborator group.
    • eligibilityRequirementId: (String, required) Unique identifier for the eligibility requirement.
    • requirementType: (String, required) Type of the requirement. For instance, "Signature".
    • document: (Object) Information about the document:
      • documentId: (String or null) Unique identifier for the document.
      • status: (String or null) Status of the document. Values include "New", "Sent", "Pending", and "Complete".
      • templateId: (String or null) Unique identifier for the template linked with the document.
      • validFor: (Number or null) Specifies the number of days the document is valid for.

Example Response

{
  "collaboratorId": "c9876543",
  "createdAt": "2023-12-01T14:45:32Z",
  "memberId": "mem890def",
  "status": "Active",
  "updatedAt": "2023-12-01T15:05:01Z",
  "userRoles": {
    "ownerIds": ["user123", "user456"],
    "viewerIds": ["user789", "user101"]
  },
  "collaboratorGroupIds": ["collab456abc", "collab123def"],
  "eligibilityRequirements": [
    {
      "clientId": "client123xyz",
      "collaboratorGroupId": "collab456abc",
      "eligibilityRequirementId": "elig123abc",
      "requirementType": "Signature",
      "document": {
        "documentId": "doc456def",
        "status": "New",
        "templateId": "tmpl789ghi",
        "validFor": 180
      }
    }
  ]
}

Updated 6 months ago