Mapping External Identifiers

Introduction

The Salesloft API is designed to serve the ecosystem of products necessary to make sellers successful. This documentation provides details on connecting a system of record to Salesloft by mapping 1 or multiple unique identifiers. This capability is essential for enterprises that want to request and map Salesloft objects using their own system IDs. The endpoints below support Salesloft People (Buyers), Accounts (Companies), and Users (Sellers).

External ID Flow

Use Cases

Use the endpoints below if:

You own an API integration that needs to identify Salesloft objects uniquely and make API calls with that identifier.
- Custom CRMs and other systems of record are supported
- Customers using a native Salesloft CRM (SFDC, HubSpot, Dynamics) are supported
You need to uniquely identify a Salesloft Person, Account, or User in multiple systems of record
You are storing unique identifiers in Salesloft custom fields and want to deprecate that implementation.

Supported Users

Salesloft Customers (Using any CRM Type or no CRM)
Salesloft Partners

Glossary

External Type: The name of your system of record. Can be generic or specific.
External ID: A unique value to identify a specific Person, Account or User
Object Type: A Salesloft Object (can be Person, Account or User)
Object ID: Salesloft’s ID for an Object. (i.e. in other parts of the platform, this is called a person_id, account_id, resource_id, etc)
Source Type: The origin point of the configuration. Will always be “Integration” for partners and customers.
Source ID: The ID of your Salesloft Integration

How It Works

Identify the systems you own that need to track Salesloft People (Buyers), Accounts (Companies), and Users (Sellers).
Create configurations that correspond with those systems.
- Best Practice: If the system of record is a vendor, consider using general terminology. (e.g. marketing_automation)
Begin making API Calls to add mappings to existing Salesloft Objects with your unique identifier.
- This is a backfill step where you will add your unique identifier to all of your existing Salesloft records.
Make any subsequent API Calls for that object, using the identifier that your system owns/knows.

Required Scopes

When setting up a configuration or mapping:

external_id_configuration:manage
external_id_configuration:read
external_id:manage
external_id:read

When requesting or upserting a Salesloft Object using your external ID:

Your API Key or OAuth application will still need traditional scopes for Salesloft objects (e.g. person:view, person:manage, account:view, etc.)

Base URL

All API endpoints are relative to the base URL: https://api.salesloft.com/v2/external

Authentication

All requests to the Salesloft API require authentication. The preferred method is OAuth using a bearer token. Include the token in the Authorization header as follows:

Authorization: Bearer {{token}}

External ID Configuration

Create a Configuration

Endpoint: POST v2/external/configurations

Requires: external_id_configuration:manage

Description: Set the name of your external identifier and choose the Salesloft object it will be related to. Your external_type could be as generic as “external_id” or as specific as the name of your system. Objects supported include People, Accounts, and Users.

Request Body Example

{
    "external_type": "external_id",
    "object_type": "accounts"
}

Response Status Code: 201 Created

API Key Response Body Example

{
    "data": {
        "deleted": false,
        "external_type": "external_id",
        "object_type": "accounts",
        "id": 123,
        "source_id": null,
        "source_type": null
    }
}

OAuth Response Body Example

{
    "data": {
        "deleted": false,
        "external_type": "external_id",
        "object_type": "accounts",
        "id": 123,
        "source_id": "integration",
        "source_type": 1121
    }
}

Source Type for integration will always be “Integration”
Source ID is your unique Salesloft Integration ID. We use this to identify your integration across our platform.

View Configurations

Endpoint: GET v2/external/configurations

Requires: external_id_configuration:read

Description: List all configurations on a Salesloft team

Response Body Example

{
    "data": [
        {
            "deleted": false,
            "external_type": "crm",
            "id": 228,
            "object_type": "users",
            "source_id": null,
            "source_type": null,

        },
        {
            "deleted": false,
            "external_type": "marketing",
            "id": 227,
            "object_type": "accounts",
            "source_id": null,
            "source_type": null
        }

    ]
}

Response Status Code: 200 OK

Create Mapping

Endpoint: POST v2/external/mappings

Requires: external_id:manage

Description: Map Salesloft People, Accounts, and Users to their unique identifiers from your system. Object_ID represents the Salesloft ID of the object.
- Notes:
  - Once a mapping is created, it cannot be updated. But it can be deleted.
  - External IDs can be the same for the same person record as long as the external type is different

Request Body Example

{
    "external_type": "crm_lead",
    "object_type": "people",
    "external_id": "CONTACT3456",
    "object_id": 578495206
}

Response Status Code: 201 Created

Response Body Example

Description: Returns details on the object that was mapped
- deleted (boolean): If the object still exists in Salesloft.
- Inserted_at: When the mapping between the two objects was made.

{
    "data":
    {
        "deleted": false,
        "external_type": "crm_lead",
        "object_type": "people",
        "external_id": "CONTACT3456",
        "inserted_at": "2024-02-01T12:00:00Z",
        "object_id": 578495206,
        "tenant_id": 100013
    }
}

View Mappings

Endpoints

GET v2/external/mappings
GET v2/external/mappings?external_id=
GET v2/external/mappings?object_type={object_type}&object_id=[1]
GET v2/external/mappings?external_type={external_type}&external_id=[1]

Requires: external_id:read

Description: List the External ID Mappings for a Salesloft Object. Can be used with Object_Type, External ID, and External_Type interchangeably
- Best Practice: Use this endpoint to resolve your External ID after getting data from the Salesloft API. Or use it to resolve an External ID to a Salesloft ID before making other API Calls

Response Status Code: 200 OK

Response Body Example - Returning a single a mapping

Description: Returns details on the object that was mapped
- deleted (boolean): If the object still exists in Salesloft.
- Inserted_at: When the mapping between the two objects was made.

    {
    "data":
    {
        "deleted": false,
        "external_type": "sdfc_account",
        "object_type": "accounts",
        "external_id": "ABC",
        "inserted_at": "2024-02-01T12:00:00Z",
        "object_id": 13,
        "tenant_id": 100013
    }
}

Response Body Example - When multiple mappings exist for a single object ID or the External ID is the same across two configurations (external types).

Use Cases:
- I want to see all the mappings that exist for this person or account.
  - /v2/external/mappings?object_id=
- I want to see all the mappings for this shared external_id.
  - /v2/external/mappings?external_id=

{
    "data":
    {
        "deleted": false,
        "external_type": "sdfc_lead",
        "object_type": "people",
        "external_id": "CONTACT3456",
        "inserted_at": "2024-02-01T12:00:00Z",
        "object_id": 207550815,
        "tenant_id": 100013
    },
    {
        "deleted": false,
        "external_type": "sdfc_contact",
        "object_type": "people",
        "external_id": "CONTACT3456",
        "inserted_at": "2024-02-01T12:00:00Z",
        "object_id": 207550815,
        "tenant_id": 100013
    }
}

Delete a Mapping

Endpoint: DELETE v2/external/mappings/id

Description: Deletes a mapping created by the user.

Response Status Code: 204

Delete a Configuration

Endpoint: DELETE v2/external/configurations/id

Description: Deletes a mapping configuration created by the user.

Response Status Code: 204

Public API Proxy

The following endpoints serve as a proxy to the relevant API endpoints. For example, when requesting People using your external IDs, Salesloft will resolve the association to those Salesloft IDs and then return the list of People. Similarly, when upserting People or Accounts, we will resolve the association to that object and upsert the person with the request payload.

List Multiple Salesloft Objects by External ID

Endpoint: GET v2/external/ids/{external_type}/{object_type}?external_ids[1]=abc

Description: Returns multiple Salesloft objects matching with that external type and ID. Can return a list of Salesloft Objects if an array of ids is passed in.
Request Method: GET

Response Body Example

{
    "data":
    {
        "id": 13,
        "email": "christopher.doe@externalid.com",
        "active": true,
        "role": "Sales Representative",
        "last_name": "Doe",
        "first_name": "Christopher"
    },
    {
        "id": 14,
        "email": "christina.doe@externalid.com",
        "active": true,
        "role": "Account Executive",
        "last_name": "Doe",
        "first_name": "Christina"
    }
}

Response Status Code: 200 OK

Upsert a Person or Account using an External ID

Endpoint: POST v2/external/ids/{external_type}/{object_type}/{external_id}

Description: This endpoint will check to see if the external ID mapping already exists for the Person or Account:
- If so, it'll proxy the request to that object's UPDATE endpoint in the public API.
- If not, it will insert a row for that external_id mapping and proxy the request to that object’s CREATE endpoint
Limitations: Does not currently support Users
Request Method: POST

Request Body Example for Person

{
    "email_address": "christoper.doe@externalid.com",
    "first_name": "Christopher",
    "last_name": "Doe",
    "account_id": 9872,
    "city": "Atlanta"
}

Response Status Code: 201 Created

Response Body Example for Person

{
 "data":
  {
   "id": 1,
   "created_at": "2023-01-01T00:00:00.000000+00:00",
   "updated_at": "2023-01-01T00:00:00.000000+00:00",
   "last_contacted_at": "2023-01-01T00:00:00.000000+00:00",
   "last_replied_at": "2023-01-01T00:00:00.000000+00:00",
   "first_name": "Christoper",
   "last_name": "Doe",
   "email_address": "christoper.doe@externalid.com",
   "city": "Atlanta",
   "custom_fields": {
     "MyField": "A Value",
     "Other": "Field"
   },
   "success_count": 1,
   "starred": false,
   "untouched": false,
   "counts": {
     "emails_sent": 3,
     "emails_viewed": 2,
     "emails_clicked": 1,
     "emails_replied_to": 0,
     "emails_bounced": 0,
     "calls": 4
    },
   "account": {
     "id": 1,
     "_href": "https://api.salesloft.com/v2/accounts/1"
   },
   "owner": {
     "id": 1,
     "_href": "https://api.salesloft.com/v2/users/1"
   },
   "last_contacted_by": {
     "id": 1,
     "_href": "https://api.salesloft.com/v2/users/1"
   },
   "most_recent_cadence": {
     "id": 1,
     "_href": "https://api.salesloft.com/v2/cadences/1"
   },
   "last_completed_step_cadence": {
     "id": 1,
     "_href": "https://api.salesloft.com/v2/cadences/1"
   },
   "last_completed_step": {
     "id": 1,
     "_href": "https://api.salesloft.com/v2/steps/1"
   },
   "cadences": [
     {
       "id": 1,
       "_href": "https://api.salesloft.com/v2/cadences/1"
     }
   ]
 }
}

Conclusion

For additional details, refer to the Salesloft API reference or submit a case to our support team.

Introduction​

Use Cases​

Supported Users​

Glossary​

How It Works​

Required Scopes​

Base URL​

Authentication​

External ID Configuration

Create a Configuration​

View Configurations​

Create Mapping​

View Mappings​

Delete a Mapping​

Delete a Configuration​

Public API Proxy

List Multiple Salesloft Objects by External ID​

Upsert a Person or Account using an External ID​

Conclusion

Introduction

Use Cases

Supported Users

Glossary

How It Works

Required Scopes

Base URL

Authentication

Create a Configuration

View Configurations

Create Mapping

View Mappings

Delete a Mapping

Delete a Configuration

List Multiple Salesloft Objects by External ID

Upsert a Person or Account using an External ID