External Identifiers

When Schedaero is integrated with a third party system, some resources in Schedaero will directly correspond to a resource in the other system.

📘
If you are integrating Schedaero with a CRM, a contact may exist in both Schedaero and the CRM. External identifiers allow you to record the external system’s unique identifier in Schedaero, and also permit users to deep-link between the two systems.

Create External System

To use external identifiers, you must first tell Schedaero about the system that you will link to Schedaero. You should record the Schedaero-assigned identifier for the system as you will need them to populate identifiers in the future.

🚧
You may create as many external systems as you require, but they must each have a unique name.

Request

POST https://sandbox-schedaero.avinode.com/api/externalsystems

{
    "name": "MyCRM"
}

Response

HTTP/1.1 201 Created
X-Avinode-ApiVersion: v1
Content-Type: application/json; charset=utf-8
Location: https://sandbox-schedaero.avinode.com/api/externalsystems/external-system-123456789

{"meta":{} }

To link a contact to an external system, PATCH the contact/system with the unique identifier for the external system’s record. The unique identifier must be unique across all Schedaero contacts linked to the same system.

Contact External Identity

Identity Attributes


identifier		Unique identifier for the contact in an external system
uri	Optional	When supplied, the Schedaero UI displays this as a deep-link to the external system
name	Optional	When supplied, the Schedaero UI displays this as the text of the deep link

UPDATE contact external identity

PATCH https://sandbox-schedaero.avinode.com/api/contacts/people/contact-123456789/externalidentity/external-system-123456789 

{
    "identifier": "ABCDEF-123456",
    "name": "CRM Customer",
    "uri": "https://app.mycrm.com/customers/edit/abcdef-123456"
}

REMOVE contact external identity

PATCH https://sandbox-schedaero.avinode.com/api/contacts/people/contact-123456789/externalidentity/external-system-123456789 

{
    "isActive": "false"
}

RETRIEVE a contact's identities

GET https://sandbox-schedaero.avinode.com/api/contacts/people/contact-123456789?fields[contact]=externalidentities

{
    "data": {
        "externalIdentities": [{
                "identifier": "ABCDEF-123456",
                "name": "CRM Customer",
                "uri": "https://app.mycrm.com/customers/edit/abcdef-123456",
                "isActive": true,
                "id": "contact-123456789/externalidentity/external-system-123456789",
                "href": "https://[REDACTED]-schedaero.avinode.local/api/contacts/people/contact-123456789/externalidentity/external-system-123456789",
                "type": "schedaero-identity"
            }
        ],
        "id": "contact-123456789",
        "href": "https://[REDACTED]-schedaero.avinode.local/api/contacts/people/contact-123456789",
        "type": "contact-person",
    },
    "meta": {}
}