External ID Types

External ID Types are objects representing each non-Addepar system or application you wish to map to an External ID. Once you’ve created a unique type for each system, use the Entities or Groups API to map them to the appropriate system/application.


Base Route	/v1/external_id_types
Endpoints	GET /v1/external_id_types /v1/external_id_types/:id POST /v1/entity_types PATCH /v1/entity_types/:id DELETE /v1/entity_types/:id
Produces	JSON
Pagination	No
Application Permissions Required	"API Access: Create, edit, and delete". "Manage firm settings: Full Access" for all operations.
OAuth Scopes	GET `ENTITIES` `GROUPS` POST, PATCH, and DELETE `ENTITIES_WRITE` `GROUPS_WRITE`

Resource Overview

External ID Types are described by the below resource object attributes and will appear in successful GET, POST & PATCH responses.

Attribute	Description	Example
`external_id_type_key`	The ID of the entity ID type. String.	`"salesforce"`
`display_name`	Display name of the entity type. String.	`"Salesforce"`

Get All External ID Types

Returns a list of all External ID Types.

GET /v1/external_id_types

Example:

GET https://examplefirm.addepar.com/api/v1/external_id_types

HTTP/1.1 200

{
  "data": [
    {
      "id": "other-external-system",
      "type": "external_id_types",
      "attributes": {
        "external_type_key": "other-external-system",
        "display_name": "Other External System"
      },
      "links": {
        "self": "/v1/external_id_types/other-external-system"
      }
    },
    {
      "id": "randomsystem",
      "type": "external_id_types",
      "attributes": {
        "external_type_key": "randomsystem",
        "display_name": "Random External System"
      },
      "links": {
        "self": "/v1/external_id_types/randomsystem"
      }
    }
  ],
  "included": [],
  "links": {
    "next": null
  }
}

Response Codes:

200 OK: Success
403 Forbidden: Insufficient application permissions

Get External ID Type By ID

Returns an External ID Type corresponding to the given ID.

GET /v1/external_id_types/:id

GET https://examplefirm.addepar.com/api/v1/external_id_types/randomsystem

HTTP/1.1 200

{
    "data": {
        "id": "randomsystem",
        "type": "external_id_types",
        "attributes": {
            "external_type_key": "randomsystem",
            "display_name": "Random External System"
        },
        "links": {
            "self": "/v1/external_id_types/randomsystem"
        }
    },
    "included": []
}

Response Codes:

200 OK: Success
403 Forbidden: Insufficient application permissions
404 Not Found: Invalid external ID type

Create an External ID Type

Adds a new External ID Type to your firm.

POST /v1/external_id_types

POST  https://examplefirm.addepar.com/api/v1/external_id_types

{
  "data": {
    "type": "external_id_types",
    "attributes": {
      "external_type_key": "randomsystem",
      "display_name": "Random External System"
    }
  }
}

HTTP/1.1 201

{
  "data": {
    "id": "randomsystem",
    "type": "external_id_types",
    "attributes": {
      "external_type_key": "randomsystem",
      "display_name": "Random External System"
    },
    "links": {
      "self": "/v1/external_id_types/randomsystem"
    }
  },
  "included": []
}

Response Codes:

201 OK: Success
403 Forbidden: Insufficient application permissions
409 Forbidden: Duplicate external_type_key

Update an External ID Type

Modifies an existing External ID Type.

PATCH /v1/external_id_types/:id

PATCH  https://examplefirm.addepar.com/api/v1/external_id_types/randomsystem

{
  "data": {
    "id": "randomsystem",
    "type": "external_id_types",
    "attributes": {
      "display_name": "Known System"
    }
  }
}

HTTP/1.1 200

{
  "data": {
    "id": "randomsystem",
    "type": "external_id_types",
    "attributes": {
      "external_type_key": "randomsystem",
      "display_name": "Known System"
    },
    "links": {
      "self": "/v1/external_id_types/randomsystem"
    }
  },
  "included": []
}

Response Codes:

201 OK: Success
403 Forbidden: Insufficient application permissions
404 Forbidden: The external ID type does not exist

Delete an External ID Type

Deletes an existing External ID Type from your firm.

DELETE /v1/external_id_types/:id

DELETE  https://examplefirm.addepar.com/api/v1/external_id_types/randomsystem

HTTP/1.1 204

Response Codes:

204 No Content: Successfully deleted the external ID type
400 Bad Request: The external ID type is associated with an Addepar object
403 Forbidden: Insufficient application permissions
404 Forbidden: The external ID type does not exist