We’re excited to announce that we’ve made a ton of improvements our API for consistency across our resources and to enable automation of even more workflows with Copilot!

Notably, we...

• Redesigned our Form and Form Response resources to make it easier to parse your clients’ answers, and update their custom fields from a form response
• Added human-readable keys to custom fields and tags (multi-select options) on clients
• Introduced a partial update (PATCH) endpoint for Clients

You can find our API documentation at docs.copilot.com. The changes mentioned below went live on June 6, 2023.

Continue reading to see the full list of changes:

All endpoints

All of our endpoints have been updated to use plural resource names in the paths. For example, /client is now /clients, /company is now /companies, etc.

Existing resources are backwards compatible with the singular resource names, but we recommend updating to the plural resource names as soon as possible.

In addition, all resource responses now use createdAt instead of created.

Clients: /clients

Update Client PATCH /clients/{id}

We have introduced a new endpoint for partial (non-destructive) update of a Client using the PATCH method.

Both PUT (destructive) and PATCH (non-destructive) requests will be made to the same endpoint: /clients/{id}

Previously, the clientId was passed to the request to v1/client in the body of the request, instead of in the path. This is backwards compatible.

We have updated the customFields structure to show custom field key/values by human-readable keys instead of IDs.

Companies: /companies

The following properties have been renamed:

leadUserID is now leadInternalUserId

assignedUserIDs is now assigneeInternalUserIds

avatarImageURL is now iconImageUrl

Custom Fields: /custom-fields

Retrieve Custom Fields GET /custom-fields

We have updated the items property to data.

id will remain the UUID of the custom field.

We have added a key property where the value will be the human-readable ID of the field. name, type, and order will remain the same.

For multi-select custom fields, the options (tags) array of objects will remain. See the Custom Fields Options section below for details regarding changes to option (tag) objects.

Custom Field Options GET /custom-fields/{id}/options

We have introduced a new resource for Custom Field Options for multi-select (tag) custom fields.

This resource will return an object for the specified custom field with an array of options (tags) for the specified field.

Each option will now have a key property where the value is a human-readable ID.

The options can now be filtered by name.

File Channels: /channels/files

List File Channels GET /channels/files

We have added a new query parameter called membershipEntityId that will allow you to filter for a file channel by the ID of the client or company.

groupType is now membershipType

memberID is now memberId

Retrieve a File Channel GET v1/channels/files/{id}

This is a new endpoint for retrieving a File Channel by its ID.

Forms: /forms

The Forms resource has been entirely redesigned. We’re now including properties related to form fields. Please see the example below:

{
    "id": "a8c2c520-8045-4068-1772-a7c8ca09ee1a",
    "createdAt": "2023-02-25T02:19:35Z",
    "object": "form",
    "fields": {
        "name": "Onboarding Form",
        "description": "Fill out this form to get started!",
        "formFieldIds": ["id0", "id1", "id2", "id3"],
        "formFields": [
            {
                "formFieldId": "id0",
                "title": "Welcome to Harry's Wizarding Consultancy!",
                "description": "Email me if you have any questions at potluck@copilot.com",
                "type": "title",
                "isRequired": false
            },
            {
                "formFieldId": "id1",
                "title": "What is your full name?",
                "description": "",
                "type": "shortAnswer",
                "isRequired": true
            },
            {
                "formFieldId": "id2",
                "title": "Upload your ID",
                "description": "You can upload multiple documents",
                "type": "fileUpload",
                "isRequired": true
            },
            {
                "formFieldId": "id3",
                "title": "Which services are you interested in?",
                "description": "",
                "type": "multiSelect",
                "multipleChoiceOptions": ["Taxes", "Family Accounting", "Advice"],
                "isRequired": false
            },
        ],
        "allowMultipleSubmissions": false,
        "visibility": "allClients"
    },
    "additionalFields": {
        "formResponseRequests": 3,
        "formResponseSubmissions": 8,
        "latestSubmissionDate": "2023-05-25T02:19:35Z"
    }
}

Form Responses: /form-responses

Request a Form Response POST /form-responses

formID is now formId

recipientID (string) is now clientIds (array)

recipientType has been removed.

Form Response Completed Webhook

The structure for the response from the Form Response Completed webhook will be entirely redesigned. Please see the example below:

{
    "id": "497b203e-2802-4212-947a-2bbc44c5f7d6",
    "object": "formResponse",
    "created": "2023-06-29T15:16:23Z",
    "formId": "a039b228-2745-4a2b-bcf7-aac56d6519bf",
    "clientId": "a076e863-a266-4efb-acea-11455779d466",
    "fields": {
      "formName": "Some Form",
      "responseStatus": "completed",
      "formFieldIds": ["id0", "id1", "id2", "id3", "id4", "id5", "id6"],
      "formFields": {
        "id0": {
          "title": "Section One",
          "description": "",
          "type": "title",
          "isRequired": false,
        },
        "id1": {
          "title": "Some Multiple Choice",
          "description": "Choose several!",
          "type": "multiSelect",
          "multipleChoiceOptions": [
            "a",
            "b",
            "c"
          ],
          "isRequired": true,
          "answer": ["a", "b"],
        },
        "bcc9ea4a-6877-4d6b-a0a0-75381b0f6146": {
          "title": "Some Single Choice",
          "description": "Choose only one!",
          "type": "singleSelect",
          "multipleChoiceOptions": [
            "a",
            "b",
            "c"
          ],
          "isRequired": true,
          "answer": "c"
        },
        "id3": {
          "title": "Section Two",
          "description": "",
          "inputType": "title",
          "required": false,
        },
        "id4": {
          "title": "Short Answer Question",
          "description": "Write an answer",
          "type": "shortAnswer",
          "isRequired": true,
          "answer": "My simple answer",
        },
        "id5": {
          "title": "Long Answer Question",
          "description": "Write an answer in the text area",
          "type": "longAnswer",
          "isRequired": true,
          "answer": "My textarea answer",
        },
        "id6": {
          "title": "Some File",
          "description": "Please upload one or more files here!",
          "type": "file",
          "isRequired": true,
          "answer": "path-to-file.pdf"
        }
      },
      "submissionDate": "2023-03-29T14:15:23Z",
      "formType": "default",
      "allowMultipleSubmissions": false,
      "visibility": "allClients"

    }
}