Manage document requirements with the API

You can assign contractors to a Collaborator Group by using the Collaborators tab in the application or by using the API.

To create an eligibility requirement for a contractor, you first need to assign them to a collaborator group.

API endpoints that are needed to configure document requirements:

Step	API endpoint
1. Upload your document	/files/files/member/public/upload
2. Create a document template	files/files/template
3. Create the eligibility requirement	payments/collaborator-settings/eligibility-requirement
4. Create a Collaborator Group	/payments/collaborator-group
5.a. Invite a Collaborator	/payments/collaborator
5.b. Get the Collaborator ID	/payments/collaborator
5.c. Add a Collaborator to a Group	/payments/collaborator/{id}/add-group/{groupId}

To create eligibility requirements with Wingspan APIs

Prerequisites

Generate or retrieve your API authorization bearer token.

Log in to Wingspan as an administrator.
From the Home page, navigate to Data & Integrations > Developer.
On the Developer page, use either the Copy or Generate new token button to retrieve your API authorization token. This token is used to authorize your calls to the Wingspan API.

1. Upload your document

Uploading a document to Wingspan is the first step in using the API to configure document signing for your contractors. After you upload the file, the response returns a file ID. The file ID is required for the next step of the procedure.

Endpoint

POST https:// api.wingspan.app/files/files/member/public/upload

Headers

accept: Specifies the format of the response from the server. Should be set to application/json to receive a JSON response.
content-type: Denotes the media type of the resource or data being sent to the server. For file uploads, this should be set to multipart/form-data.
authorization: Provides authentication using a bearer token. Replace with the actual token for authentication.

Request Parameters

file: The file to be uploaded. Use the -F option followed by file=@<FILE_PATH> where <FILE_PATH> is the path to your file.

Example: -F 'file=@/path/to/file.pdf'

Example Request

curl --request POST \
     --url https://api.wingspan.app/files/files/member/public/upload \
     --header 'accept: application/json' \
     --header 'content-type: multipart/form-data' \
     --header 'authorization: Bearer <YOUR TOKEN>' \
     -F 'file=@/path/to/file.pdf'

Response

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

Response Body

The response is a JSON object containing the following fields:

createdAt: (String, required) The timestamp when the file was created.
eventActors: (Object, required) Contains additional fields related to the entities involved in the event.
fileAccessScope: (String, required) Describes the scope of file access. Values are Private, Public, and Internal.
fileId: (String, required) A unique identifier for the uploaded file. Make note of the file ID as it is needed for the next step in the procedure.
filename: (String, required) The name of the uploaded file.
gcsBucketName: (String, required) The name of the Google Cloud Storage bucket where the file resides.
labels: (Object, required) Contains additional metadata or categorizations for the file. memberId: (String, required) The unique identifier for the member who owns the file.
updatedAt: (String, required) The timestamp when the file was last updated.
url: (String, required) The public URL to access the uploaded file.
userRoles: (Object, required)
- ownerIds: (Array of Strings, required) The list of user IDs who have ownership rights over the file.
- viewerIds: (Array of Strings, required) The list of user IDs who have viewing rights over the file.
encoding: (String | null) The encoding type of the file, if available.
mimetype: (String | null) The MIME type of the file, if available.

Example Response

{
    "createdAt": "2023-09-24T10:30:00Z",
    "eventActors": {
        "actorId": "a98765",
        "actorType": "user"
    },
    "fileAccessScope": "Public",
    "fileId": "f1234567890",
    "filename": "sample-file.pdf",
    "gcsBucketName": "wingspan-files-bucket",
    "labels": {
        "category": "document",
        "type": "report"
    },
    "memberId": "m1234567",
    "updatedAt": "2023-12-01T10:30:00Z",
    "url": "https://wingspan.storage.googleapis.com/sample-file.pdf",
    "userRoles": {
        "ownerIds": ["u12345", "u67890"],
        "viewerIds": ["u11223", "u44556", "u77889"]
    },
    "encoding": "UTF-8",
    "mimetype": "application/pdf"
}

Ensure that you retrieve the fileId from the response body, as it is needed to create a document template.

2. Create a document template

This API endpoint allows a company to specify which party or role is responsible for acting on a document template. This is useful for tasks like onboarding a collaborator, where specific roles may need to review, approve, or fill out certain documents.

Endpoint

POST https://api.wingspan.app/files/files/template

Headers

accept: Specifies the expected format of the response from the server. It should be set to application/json to receive a JSON-formatted response.
content-type: Denotes the media type of the data being sent to the server. For this request, it should be set to application/json.
authorization: Provides authentication credentials for the request. Replace with your actual bearer token for authentication.

Request Payload

The body of the request should contain the following JSON fields:

purpose: The purpose or intention behind the document. Example: "OnboardCollaborator".
fileId: The unique identifier associated with the file or document in question.
title: The title or name of the document.
roles: An array of roles that are relevant or responsible for acting upon the document. Possible roles might include "Client", "Collaborator", and "Member".

Example Request

curl --request POST \
     --url https://api.wingspan.app/files/files/template \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer <YOUR TOKEN>' \
     --data '{
  "purpose": "OnboardCollaborator",
  "fileId": "123asd",
  "title": "The name of the document",
  "roles": [
    "Client",
    "Collaborator",
    "Member"
  ]
}'

Response

Upon successful submission, the API returns a status code of 200.

Response Body

The successful response is a JSON object containing:

clientId: (String, required) The unique identifier for the client.
editUrl: (String, required) A URL that provides editing access to the document.
editUrlExpiresAt: (String, required) The timestamp indicating when the edit URL will expire.
fileId: (String, required) A unique identifier for the associated file or document.
purpose: (String, required) The specified purpose of the document, e.g., "OnboardCollaborator".
templateId: (String, required) The unique identifier for the document template.
title: (String, required) The title or name of the document.
roles: (Array of Strings | null) The list of roles associated with the document, or null if no roles are specified.
viewUrl: (String | null) A URL that provides view-only access to the document, or null if not provided.
viewUrlExpiresAt: (String | null) The timestamp indicating when the view URL will expire, or null if not provided.

Example response

{
    "clientId": "c9876543",
    "editUrl": "https://wingspan.app/editor/123asd/edit",
    "editUrlExpiresAt": "2023-12-02T12:00:00Z",
    "fileId": "123asd",
    "purpose": "OnboardCollaborator",
    "templateId": "tmpl456xyz",
    "title": "The name of the document",
    "roles": ["Client", "Collaborator", "Member"],
    "viewUrl": "https://wingspan.app/viewer/123asd/view",
    "viewUrlExpiresAt": "2023-10-01T12:00:00Z"
}

Now that a template is created for your document and you have retrieved the templateId, you can assign eligibility requirements, such as requiring a signature on an NDA, to that document.

3. Create the eligibility requirement

In the process of considering contractors for a contract position, there may be specific actions that need to be executed on certain documents. The API endpoint documented below facilitates this by allowing a company to assign what is termed as an "eligibility requirement" to a document. An example of requirement is the need for a contractor to sign a Non-Disclosure Agreement (NDA) before being considered for a contractual role.

This call creates an eligibilityRequirementId to the document. The eligibilityRequirementId is used in the next step of the procedure to assign specific document requirements to Collaborator Groups.

Endpoint

POST https://api.wingspan.app/payments/collaborator-settings/eligibility-requirement

Headers

accept: This header specifies the expected format of the response from the server. Set this to application/json to receive a JSON-formatted response.
content-type: This header indicates the media type of the data being sent to the server. For this specific request, ensure it is set to application/json.
authorization: Provides authentication credentials for the request. Replace with your actual bearer token for authentication.

Request Payload

The body of your request should be a JSON object containing:

requirementType: Describes the type of action or requirement. For instance, "Signature" denotes that a signature is required on the document.
templateId: This is the unique identifier associated with the document or file template that has the eligibility requirement.
validFor: Indicates the number of days the requirement is valid for. For example, a value of 365 would mean the requirement is valid for a year from its assignment.

Example Request

curl --request POST \
     --url https://api.wingspan.app/payments/collaborator-settings/eligibility-requirement \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "requirementType": "Signature",
  "templateId": "tmpl456xyz",
  "validFor": 365
}'

Response

If the eligibility requirement is successfully assigned to a document, the API will return a status code of 200.

Response Body

The response will be a JSON object containing:

clientId: (String, required) The unique identifier for the client.
eligibilityRequirementId: (String, required) A unique identifier for the assigned eligibility requirement. Make a note of this ID as it is required for the next step in the procedure.
requirementType: (String, required) The type of requirement that has been set, in this case, "Signature".
templateId: (String | null) The identifier of the document or file template.
validFor: (Number | null) The number of days the requirement is valid for, or null if not specified.

Example Response

{
    "clientId": "c9876543",
    "eligibilityRequirementId": "req12345abcd",
    "requirementType": "Signature",
    "templateId": "tmpl456xyz",
    "validFor": 365
}

Ensure that you record the eligibilityRequirementId as it is used in the next step of the procedure to assign specific document requirements to Collaborator Groups.

4. Create a Collaborator Group

The given API call allows you to create a new collaborator group with specific eligibility requirements. When the call is successful and the Collaborator Group is created, a collaboratorGroupId is assigned to the Collaborator and is returned in the response body of the call. Make note of the collaboratorGroupId as it is needed when adding Collaborators to the group.

Endpoint

POST https://api.wingspan.app/payments/collaborator-group

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 Body Parameters

The API accepts the following parameters in the request body:

description: (String) A textual representation providing details about the collaborator group.
Example: Collaborator Group for Construction Project 1.
name: (String) The name of the collaborator group.
Example: "Construction Project 1"
eligibilityRequirements: (Array) A list of eligibility requirements a contractor must act on to be considered for a job. Each object in the array must contain the following key:
- eligibilityRequirementId: (String) The ID of NDAs or contracts.
  Example:
```
[
        {
          "eligibilityRequirementId": "123asd"
        },
        {
          "eligibilityRequirementId": "456qwe"
        }
      ]
```

Example Request

curl --request POST \
     --url https://api.wingspan.app/payments/collaborator-group \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer <Your bearer token>' \
     --data '
{
  "description": "This is a description of the collaborator group",
  "name": "This is the name of the collaborator group",
  "eligibilityRequirements": [
    {
      "eligibilityRequirementId": "123asd"
    },
    {
      "eligibilityRequirementId": "456qwe"
    },
    {
      "eligibilityRequirementId": "789iop"
    }
  ]
}'

Response

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

Response Body

The response is a JSON object with the following keys:

clientId: (String, required) The unique ID associated with the client.
collaboratorGroupId: (String, required) The unique ID of the newly created collaborator group.
defaultGroup: (Boolean, required) Indicates whether the group is a default group or not.
description: (String, required) The description of the collaborator group provided in the request.
name: (String, required) The name of the collaborator group provided in the request.
eligibilityRequirements: (Array | null) An array of the eligibility requirement IDs provided in the request, or null if none were provided.

Example Response

{
    "clientId": "c1234567890",
    "collaboratorGroupId": "g0987654321",
    "defaultGroup": false,
    "description": "Description of the collaborator group",
    "name": "Name of the collaborator group",
    "eligibilityRequirements": [
        {
            "eligibilityRequirementId": "123asd"
        },
        {
            "eligibilityRequirementId": "456qwe"
        },
        {
            "eligibilityRequirementId": "789iop"
        }
    ]
}

Ensure that you record the collaboratorGroupId as it is used in the next step of the procedure to assign Collaborators to Collaborator Groups.

5. Add Collaborators to Collaborator Groups

There are two ways to add a Collaborator to Collaborator Groups: by assigning an existing contractor to an existing Collaborator Group and by inviting a new contractor to be a Collaborator on your project in Wingspan. Adding an existing Collaborator to an existing Collaborator Group requires the Collaborator ID as well as the Collaborator group ID and uses the payments/collaborator/{id}/add-group/{groupId} endpoint. Inviting a new contractor uses the /payments/collaborator endpoint and requires the contractors email address.

5.a. Assign an existing Collaborator to a Collaborator Group

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"
    }
]

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
      }
    }
  ]
}

5.b. Invite a contractor

This API endpoint is used to invite a contractor to join your project as a collaborator. By using this endpoint, you can simultaneously invite contractors via their email address and assign them to a specific collaborator group using a collaborator group ID.

Endpoint

POST 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

The request payload must be a JSON object with the following properties:

clientId (string, Required): The unique identifier for the client.
memberCompany (string, Optional): The name of the company the member belongs to.
memberEmail (string, Optional): The email address of the contractor to be invited.
memberName (string, Optional): The name of the contractor to be invited.
collaboratorGroupId (string, Optional): The unique identifier for the collaborator group to which the member will be assigned.

Example Request

{
  "memberCompany": "Construction Central",
  "clientId": "123asd",
  "memberEmail": "[email protected]",
  "memberName": "Jon Smith",
  "collaboratorGroupId": "123asd"
}

Response

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

collaboratorId (string, Required): The unique identifier for the collaborator.
createdAt (string, Required): Timestamp indicating when the collaborator was created.
memberId (string, Required): The unique identifier for the member.
status (string, Required): Indicates the status of the collaborator. It could be Active, Inactive, or Pending.
updatedAt (string, Required): Timestamp indicating the last time the collaborator information was updated.
userRoles (object, Required): Contains ownerIds (array of strings, Required) and viewerIds (array of strings, Required).
collaboratorGroupIds (array of strings, Optional): The groups to which the collaborator belongs.
eligibilityRequirements (array, Optional): An array of objects representing the eligibility requirements for the collaborator.