Drift REST API
Drift REST API covers contacts, users, conversations and messages, accounts, playbooks, teams, app admin tokens, data privacy, and SCIM provisioning. Webhook events deliver realtime conversation, contact, and message updates.
OpenAPI Specification
openapi: 3.0.0
info:
title: Drift
description: >-
Drift is a cloud-based solution designed to help businesses automate sales
processes by adding live chat windows to websites for increased customer
experience and loyalty. Key features include chatbots, geo-targeting,
offline access, proactive chating and transfers/routing.
version: 1.0.0
servers:
- url: http://{{base_url}}
- url: https://driftapi.com
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
security:
- bearerAuth: []
tags:
- name: Accounts
- name: App Admin
description: >-
[https://devdocs.drift.com/docs/app-uninstall](https://devdocs.drift.com/docs/app-uninstall)
- name: Contacts
description: >-
[https://devdocs.drift.com/docs/contact-model](https://devdocs.drift.com/docs/contact-model)
- name: Conversations and Messages
description: >-
[https://devdocs.drift.com/docs/conversation-model](https://devdocs.drift.com/docs/conversation-model)
- name: Data Privacy
description: >-
[https://devdocs.drift.com/docs/automating-gdpr-retrieval-and-deletion](https://devdocs.drift.com/docs/automating-gdpr-retrieval-and-deletion)
- name: Playbooks
description: >-
[https://devdocs.drift.com/docs/playbook-model-1](https://devdocs.drift.com/docs/playbook-model-1)
- name: SCIM API
- name: Teams
description: >-
[https://devdocs.drift.com/docs/team-model](https://devdocs.drift.com/docs/team-model)
- name: Users
description: >-
[https://devdocs.drift.com/docs/user-model](https://devdocs.drift.com/docs/user-model)
paths:
/contacts:
post:
tags:
- Contacts
summary: Drift Create a contact
requestBody:
content:
application/json:
schema:
type: object
example:
attributes:
email: string
responses:
'200':
description: Successful response
content:
application/json: {}
get:
tags:
- Contacts
summary: Drift List contacts by externalId
parameters:
- name: idType
in: query
schema:
type: string
example: external
- name: id
in: query
schema:
type: string
description: Your unique externalId
responses:
'200':
description: Successful response
content:
application/json: {}
/contacts/{id}:
patch:
tags:
- Contacts
summary: Update a contact - Drift Id
requestBody:
content:
application/json:
schema:
type: object
example:
attributes:
attribute_name: value
parameters:
- name: id
in: path
schema:
type: string
required: true
description: Drift contactId
responses:
'200':
description: Successful response
content:
application/json: {}
get:
tags:
- Contacts
summary: Fetch a contact by Drift Id
parameters:
- name: id
in: path
schema:
type: string
required: true
description: Drift contactId
responses:
'200':
description: Successful response
content:
application/json: {}
post:
tags:
- Contacts
summary: Drift Delete a contact
requestBody:
content: {}
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
description: Successful response
content:
application/json: {}
/contacts/normalize:
patch:
tags:
- Contacts
summary: Drift Update a contact - ExternalId
requestBody:
content:
application/json:
schema:
type: object
example:
attributes:
attribute_name: value
parameters:
- name: idType
in: query
schema:
type: string
description: One of drift, external, internal
- name: id
in: query
schema:
type: string
description: Your unique externalId
responses:
'200':
description: Successful response
content:
application/json: {}
/contacts/:
get:
tags:
- Contacts
summary: Drift List contacts by email
parameters:
- name: email
in: query
schema:
type: string
description: The email address of the requested contact
responses:
'200':
description: Successful response
content:
application/json: {}
/emails/unsubscribe:
post:
tags:
- Contacts
summary: Drift Unsubscribe contacts from emails
requestBody:
content:
application/json:
schema:
type: object
example:
- [email protected]
responses:
'200':
description: Successful response
content:
application/json: {}
/contacts/timeline:
post:
tags:
- Contacts
summary: Drift Post a timeline event to a contact - externalId
requestBody:
content:
application/json:
schema:
type: object
example:
externalId: 0
createdAt: 0
event: string
responses:
'200':
description: Successful response
content:
application/json: {}
/contacts/attributes:
get:
tags:
- Contacts
summary: Drift List custom contact attributes
responses:
'200':
description: Successful response
content:
application/json: {}
/users/{id}:
get:
tags:
- Users
summary: Drift Fetch a user
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
description: Successful response
content:
application/json: {}
/users/list:
get:
tags:
- Users
summary: Drift List all users
responses:
'200':
description: Successful response
content:
application/json: {}
/users/update:
patch:
tags:
- Users
summary: Drift Update a user
requestBody:
content:
application/json:
schema:
type: object
example: {}
parameters:
- name: userId
in: query
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json: {}
/users/meetings/org:
get:
tags:
- Users
summary: Drift Fetch booked meetings
parameters:
- name: min_start_time
in: query
schema:
type: string
- name: max_start_time
in: query
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json: {}
/conversations/{id}/messages:
post:
tags:
- Conversations and Messages
summary: Drift Create a message
requestBody:
content:
application/json:
schema:
type: object
example:
type: string
body: string
buttons:
- value: string
label: string
type: string
userId: 0
parameters:
- name: id
in: path
schema:
type: string
required: true
description: The Drift conversationId
responses:
'200':
description: Successful response
content:
application/json: {}
get:
tags:
- Conversations and Messages
summary: Drift Fetch a conversation's messages
parameters:
- name: next
in: query
schema:
type: string
description: Page number where page sizes are always 50
- name: id
in: path
schema:
type: string
required: true
description: The Drift conversationId
responses:
'200':
description: Successful response
content:
application/json: {}
/conversations/{id}:
get:
tags:
- Conversations and Messages
summary: Drift Fetch a conversation
parameters:
- name: id
in: path
schema:
type: string
required: true
description: The Drift conversationId
responses:
'200':
description: Successful response
content:
application/json: {}
/conversations/{id}/transcript:
get:
tags:
- Conversations and Messages
summary: Drift Fetch a conversation's transcript as a string
parameters:
- name: id
in: path
schema:
type: string
required: true
description: The Drift conversationId
responses:
'200':
description: Successful response
content:
application/json: {}
/conversations/{id}/json_transcript:
get:
tags:
- Conversations and Messages
summary: Drift Fetch a conversation's transcript as a JSON object
parameters:
- name: id
in: path
schema:
type: string
required: true
description: The Drift conversationId
responses:
'200':
description: Successful response
content:
application/json: {}
/attachments/{id}/data:
get:
tags:
- Conversations and Messages
summary: Drift Fetch a conversation's attachments
parameters:
- name: id
in: path
schema:
type: string
required: true
description: The Drift documentId
responses:
'200':
description: Successful response
content:
application/json: {}
/conversations/new:
post:
tags:
- Conversations and Messages
summary: Drift Create a conversation
requestBody:
content:
application/json:
schema:
type: object
example:
email: string
message:
body: string
attributes: {}
responses:
'200':
description: Successful response
content:
application/json: {}
/conversations/stats:
get:
tags:
- Conversations and Messages
summary: Drift List conversation statuses
responses:
'200':
description: Successful response
content:
application/json: {}
/conversations/list:
get:
tags:
- Conversations and Messages
summary: Drift List conversations
parameters:
- name: limit
in: query
schema:
type: string
description: Max number of conversations to retrieve (max 100, default 25).
- name: statusId
in: query
schema:
type: string
description: >-
Return only conversations that match the provided status code. Uses
the following values: OPEN, CLOSED, PENDING
- name: page_token
in: query
schema:
type: string
description: Allows you to move to the next page
responses:
'200':
description: Successful response
content:
application/json: {}
/accounts/create:
post:
tags:
- Accounts
summary: Drift Create an account
requestBody:
content:
application/json:
schema:
type: object
example:
owner_id: 0
name: string
domain: string
customProperties:
- label: string
name: string
value: 0
type: NUMBER
targeted: true
responses:
'200':
description: Successful response
content:
application/json: {}
/accounts/{id}:
get:
tags:
- Accounts
summary: Drift Fetch an account
parameters:
- name: id
in: path
schema:
type: string
required: true
description: Drift accountId
responses:
'200':
description: Successful response
content:
application/json: {}
delete:
tags:
- Accounts
summary: Drift Delete an account
parameters:
- name: id
in: path
schema:
type: string
required: true
description: Drift accountId
responses:
'200':
description: Successful response
content:
application/json: {}
/accounts:
get:
tags:
- Accounts
summary: Drift List accounts
parameters:
- name: index
in: query
schema:
type: string
description: >-
Used as a starting index of the the accounts query in the
authenticated Drift user's account
- name: size
in: query
schema:
type: string
description: Number of accounts per batch (default=10, max=65)
responses:
'200':
description: Successful response
content:
application/json: {}
/accounts/update:
patch:
tags:
- Accounts
summary: Drift Update an account
requestBody:
content:
application/json:
schema:
type: object
example:
ownerId: 0
name: string
accountId: string
domain: string
customProperties:
- label: string
name: string
value: 0
type: NUMBER
targeted: true
responses:
'200':
description: Successful response
content:
application/json: {}
/playbooks/list:
get:
tags:
- Playbooks
summary: Drift List playbooks
responses:
'200':
description: Successful response
content:
application/json: {}
/playbooks/clp:
get:
tags:
- Playbooks
summary: Drift List conversational landing pages (CLP)
responses:
'200':
description: Successful response
content:
application/json: {}
/teams/org:
get:
tags:
- Teams
summary: Drift List teams
responses:
'200':
description: Successful response
content:
application/json: {}
/teams/users/{id}:
get:
tags:
- Teams
summary: Drift List teams by user
parameters:
- name: id
in: path
schema:
type: string
required: true
description: Drift userId
responses:
'200':
description: Successful response
content:
application/json: {}
/app/uninstall:
post:
tags:
- App Admin
summary: Drift Trigger app uninstall
requestBody:
content: {}
parameters:
- name: clientId
in: query
schema:
type: string
example: ':clientId'
- name: clientSecret
in: query
schema:
type: string
example: ':clientSecret'
responses:
'200':
description: Successful response
content:
application/json: {}
/app/token_info:
post:
tags:
- App Admin
summary: Drift Get token information
requestBody:
content:
application/json:
schema:
type: object
example:
access_token: string
responses:
'200':
description: Successful response
content:
application/json: {}
/gdpr/retrieve:
post:
tags:
- Data Privacy
summary: Drift Fetch GDPR data
requestBody:
content:
application/json:
schema:
type: object
example:
email: string
responses:
'200':
description: Successful response
content:
application/json: {}
/gdpr/delete:
post:
tags:
- Data Privacy
summary: Drift Delete GDPR data
requestBody:
content:
application/json:
schema:
type: object
example:
email: string
responses:
'200':
description: Successful response
content:
application/json: {}
/scim/Users:
get:
tags:
- SCIM API
summary: Drift List user objects
responses:
'200':
description: Successful response
content:
application/json: {}
post:
tags:
- SCIM API
summary: Drift Provision a user
requestBody:
content:
application/json:
schema:
type: object
example:
schemas:
- urn:scim:schemas:core:2.0
userName: stgring
displayName: string
roles:
- value: string
display: string
primary: true
name:
givenName: string
familyName: string
formatted: string
phoneNumbers:
- value: string
display: string
primary: true
locale: string
responses:
'200':
description: Successful response
content:
application/json: {}
put:
tags:
- SCIM API
summary: Drift Update a user
requestBody:
content:
application/json:
schema:
type: object
example:
schemas:
- urn:scim:schemas:core:2.0
userName: stgring
displayName: string
roles:
- value: string
display: string
primary: true
name:
givenName: string
familyName: string
formatted: string
phoneNumbers:
- value: string
display: string
primary: true
locale: string
responses:
'200':
description: Successful response
content:
application/json: {}
delete:
tags:
- SCIM API
summary: Drift Deprovision a user
responses:
'200':
description: Successful response
content:
application/json: {}
/scim/Users/{id}:
get:
tags:
- SCIM API
summary: Drift Fetch a user object
parameters:
- name: id
in: path
schema:
type: string
required: true
description: Drift userId
responses:
'200':
description: Successful response
content:
application/json: {}