Introduction

Welcome to Demandbase's API!

What can our API do?

Today, our API allows read-only access to your Analytics data, as well as some administrative management functions. Specifically, you can:

Get Accounts
Get People
Get Activites
Get Account Lists
Manage users

Authentication

For authentication, there are two choices:

Use basic authentication with your Demandbase API token as the username and an empty password.
Pass a header like: Authorization: Bearer v334asfsdfo3241ERqwefe
- The part after "Bearer" is your API token.

Accounts

GET /accounts/fields

curl \
  "https://gateway.demandbase.com/api/v1/accounts/fields" \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/accounts/fields',
    method: 'GET'
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

[
  {
    "name": "{Account}.engagementMinutesLast7Day",
    "label": "# Play Steps Resolved (all time)",
    "dataType": "Long",
    "pickListValues": [],
    "cardinality": -1,
    "status": "Normal",
    "referenceTo": []
  }
]

HTTP Request

GET https://gateway.demandbase.com/api/v1/accounts/fields

The Account Fields endpoint returns a list of all fields that are available to be returned via the /accounts endpoint.

GET /accounts

curl \
  -G "https://gateway.demandbase.com/api/v1/accounts" \
  -d "accountList=39&fields={Account}.engagementMinutesLast7Day&filters={"field": "{Account}.sfdcId", "operator": "Equals", "values":["0011a00000DpxW3AAJ", "0011a00000DpxbJAAR"]}&format=json" \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/accounts?accountList=39&fields={Account}.engagementMinutesLast7Day&filters={"field": "{Account}.sfdcId", "operator": "Equals", "values":["0011a00000DpxW3AAJ", "0011a00000DpxbJAAR"]}&format=json',
    method: 'GET'
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

[
  {
    "{Account}.engagementMinutesLast7Days": 216.54,
    "{Account}.id": 6
  },
  {
    "{Account}.engagementMinutesLast7Days": 122.24199999999998,
    "{Account}.id": 8
  }
]

The Accounts endpoint returns a CSV file or JSON blob that contains details about accounts in an Demandbase account list. Use the fields parameter to specify the desired fields to return.

❗ Either accountList or account parameter must be provided as well as at least one of the fields you want.

HTTP Request

GET https://gateway.demandbase.com/api/v1/accounts

Query Parameters

Parameter	Type	Description
fields	query string[], multiple parameters (fields=aaa&fields=bbb)	Names of fields to return. Call /accounts/fields to learn available fields.
accountList	query integer	Description: ID of the Demandbase account list whose accounts should be returned.
filters	query object[], multiple parameters (filters=aaa&filters=bbb)	Description: Filters to apply to limit the data returned.
format	query string (i.e. &format=json)	Description: Specify JSON to receive output as a JSON object as opposed to the .csv file output.
from	Type of Param: query string (ISO date)	Description: The start date for the date range used for engagement-related fields, in ISO format.
to	Type of Param: query string (ISO date)	Description: The end date for the date range used for engagement-related fields, in ISO format.

Responses

A CSV file with one row per account and one column per requested field, unless "format=json" was specified

Invalid request

Server error occurred

People

GET /people/fields

curl \
  "https://gateway.demandbase.com/api/v1/people/fields" \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/people/fields',
    method: 'GET'
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

[
  {
    "name": "{Person}.company",
    "label": "Company",
    "dataType": "String",
    "pickListValues": [],
    "cardinality": -1,
    "status": "Normal",
    "referenceTo": []
  }
]

HTTP Request

GET https://gateway.demandbase.com/api/v1/people/fields

The People Fields endpoint returns a list of all fields that are available to be returned via the /people endpoint. This will return not only available people fields but also related account fields (just like in our application).

GET /people

curl \
  -G "https://gateway.demandbase.com/api/v1/people" \
  -d "accountList=39&fields={Person}.company&format=json" \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/people?accountList=39&fields={Person}.company&format=json',
    method: 'GET'
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

[
  {
    "{Person}.company": "BloomReach",
    "{Person}.id": 21812
  },
  {
    "{Person}.company": "BloomReach",
    "{Person}.id": 21748
  }
]

The People endpoint returns a CSV file or JSON blob that contains details about people in an Demandbase account list. Use the fields parameter to specify the desired fields to return.

❗ Either accountList or account parameter must be provided as well as at least one of the fields you want.

HTTP Request

GET https://gateway.demandbase.com/api/v1/people

Query Parameters

Parameter	Type	Description
fields	query string[] , multiple parameters (fields=aaa&fields=bbb)	Names of fields to return. Call /accounts/fields to learn available fields.
accountList	query integer	ID of the Demandbase account list whose people should be returned.
account	query integer	ID of the Demandbase account to return data for.
filters	query object[] , multiple parameters (filters=aaa&filters=bbb)	Filters to apply to limit the data returned.
format	query string (i.e. &format=json)	Specify JSON to receive output as a JSON object as opposed to the .csv file output.
from	query string (ISO date)	The start date for the date range used for engagement-related fields, in ISO format.
to	query string (ISO date)	The end date for the date range used for engagement-related fields, in ISO format.

Responses

A CSV file with one row per person and one column per requested field, unless "format=json" was specified

Invalid request

Server error occurred

Activities

GET /activities/fields

curl \
  "https://gateway.demandbase.com/api/v1/activities/fields" \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/activities/fields',
    method: 'GET'
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

[
  {
    "name": "{Activity}.category___e",
    "label": "Category",
    "dataType": "String",
    "pickListValues": [],
    "cardinality": -1,
    "status": "Normal",
    "referenceTo": []
  }
]

HTTP Request

GET https://gateway.demandbase.com/api/v1/activities/fields

The Activities Fields endpoint returns a list of all fields that are available to be returned via the /activities endpoint. This will return not only available activity fields but also related people and account fields (just like in our application).

GET /activities

curl \
  -G "https://gateway.demandbase.com/api/v1/activities" \
  -d "accountList=39&fields={Activity}.category___e&format=json" \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/activities?accountList=39&fields={Activity}.category___e&format=json',
    method: 'GET'
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

[
  {
    "{Activity}.category___e": "Marketing Email Open",
    "{Activity}.id":3593215
  },
  {
    "{Activity}.category___e": "Marketing Email Open",
    "{Activity}.id":3769345
  }
]

The Activities endpoint returns a CSV file or JSON blob that contains details about activities in an Demandbase account list. Use the fields parameter to specify the desired fields to return.

❗ Either accountList or account parameter must be provided as well as at least one of the fields you want.

HTTP Request

GET https://gateway.demandbase.com/api/v1/activities

Query Parameters

Parameter	Type	Description
fields	query integer	Names of fields to return. Call /activities/fields to learn available fields.
accountList	query integer	ID of the Demandbase account list whose activities should be returned.
account	query integer	ID of the Demandbase account to return data for.
filters	query object[], multiple parameters (filters=aaa&filters=bbb)	Filters to apply to limit the data returned.
format	query string (i.e. &format=json)	Specify JSON to receive output as a JSON object as opposed to the .csv file output.
from	query string (ISO date)	The start date for the date range used for engagement-related fields, in ISO format.
to	query string (ISO date)	The end date for the date range used for engagement-related fields, in ISO format.

Note: if you want to get activities for certain people/accounts, all activities have an {Account}.id and {People}.id. Find the accounts/people you need by making a request to the corresponding endpoint and pass in the ids to the filter in your activity request.

Responses

A CSV file with one row per activity and one column per requested field, unless "format=json" was specified

Invalid request

Server error occurred

AccountLists

GET /accountlists

curl \
  "https://gateway.demandbase.com/api/v1/accountLists" \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/accountLists',
    method: 'GET'
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

[
  {
    "id": 213,
    "name": "Accounts with Opps - Presentation/Demo Stage"
  }
]

HTTP Request

GET https://gateway.demandbase.com/api/v1/accountLists

The AccountLists endpoint returns a JSON blob that contains a list of account lists in Demandbase.

Responses

A JSON blob with the name and id of each account list

Invalid request

Server error occurred

How to find an AccountList id outside of the API

While the new accountLists API may be the easiest way to access the list ID, the other way to get the list ID is through the Demandbase web application UI -- if you select the account list from the box in the top left, then the account list ID shows up as a path component in the URL (see screenshot below).

Accountlists

User Management

GET /usersByEmail

curl \
  "https://gateway.demandbase.com/api/v1/usersByEmail" \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/usersByEmail',
    method: 'GET'
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

[
  {
    "id": 1234,
    "fullName": "Full Name",
    "email": "Email Address",
    "role": 1
  }
]

HTTP Request

GET https://gateway.demandbase.com/api/v1/usersByEmail

The Users by Email endpoint returns a list of all users.

POST /user

curl \
  -G "https://gateway.demandbase.com/api/v1/user" \
  -X POST
  -d '{"email":"foo@barnum.com","fullName":"Foo Barnum","role":1,"department":"marketing"}' \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/user',
    method: 'POST',
    body: JSON.stringify({"email":"foo@barnum.com","fullName":"Foo Barnum","role":1,"department":"marketing"})
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

{
  "tenant": {
    "id": 1234,
    "name": "tenant",
    "dbName": "c1234_tenant",
    "createdDate": "2020-08-07T19:37:07Z",
    "domain": "yourdomain.com",
    "emailTech": "Gmail",
    "settings": {
      "demo": true,
      "sku": {
        "Dash": true
      },
      "bomboraUniverseListId": 5262,
      "preferredEngagementMinsSource": "Marketo",
      "taskCategoryField": "Type",
      "isBomboraPaidCustomer": true,
      "csActivityLevelUpload": {
        "uploadHubSpot": true,
        "uploadCampaign": true,
        "uploadOutreach": true,
        "uploadSalesloft": true
      },
      "serviceLevel": "Executive",
      "scout": {
        "profileTwitterField": "_createdbyexternalparty_value",
        "showSidePanelTab": true,
        "showRunPlay": true,
        "profileLinkedinField": "_ownerid_value",
        "profilePictureField": "_createdby_value",
        "showCommunicationHistory": true
      },
      "bomboraUniverseListLabel": "+test",
      "fiscalYearStartMonth": 2,
      "isEmailServiceAccountFeatureEnabled": true,
      "isShowingOpportunityScreen": true,
      "accountListsForOwners": true
    },
    "domainHash": "sadfafafawfawfsafdccceceacsddascac",
    "softwareLevel": "prod",
    "passwordSecurity": "NORMAL",
    "passwordAuth": true,
    "salesforceAuth": true,
    "googleAppAuth": false,
    "googleAppBasicAuth": false,
    "samlAuth": false,
    "emailLockType": 2,
    "emailLockUsers": [],
    "activityUploadLevel": 512,
    "exchangeServerUrl": null,
    "dbServerIndex": 0,
    "maintenanceMode": 0,
    "authScope": 0,
    "tenancy": "D",
    "serviceAccountEnabled": true,
    "connectionModeOverwrite": "CONNECTED_CRM",
    "salesforceAccountId": null,
    "licenseAgreementRequired": false,
    "demo": false
  },
  "user": {
    "id": 106798,
    "email": "foo@barnum.com",
    "fullName": "Foo Barnum",
    "createdAt": "2021-03-11T02:10:36Z",
    "validatedAt": null,
    "passwordExpiresAt": "1970-01-01T00:00:00Z",
    "firstName": null,
    "lastName": null,
    "title": null,
    "phone": null,
    "dialerPhone": null,
    "profilePicture": null,
    "signature": null,
    "department": "marketing",
    "settings": {},
    "hasGooglePermission": false,
    "emailTrustUsers": [
      -1
    ],
    "passwordAuth": true,
    "salesforceAuth": false,
    "googleAppAuth": false,
    "googleAppBasicAuth": false,
    "samlAuth": false,
    "createdBy": "vramesh@demandbase.com",
    "expired": false,
    "requireApproval": false
  },
  "role": 1,
  "priority": 1,
  "accessLevel": 0,
  "settings": {},
  "id": 107441
}

The Create User endpoint creates a Demandbase One user for your tenant.

❗ Email must be provided and the new user will receive an email to complete activation of their Demandbase One account.

HTTP Request

POST https://gateway.demandbase.com/api/v1/user

Request Body

Parameter	Type	Description
email	string	Email address
fullName	string	Display name
role	int	1 for general, 3 for admin
department	string	Department (default is marketing)
view	int	View management ID (optional, defaults to system view)

Responses

Created user json

Invalid request

Server error occurred

PUT /user/{userId}

curl \
  -G "https://gateway.demandbase.com/api/v1/user/106798" \
  -X PUT
  -d '{"fullName":"Bar Foonum", "department": "sales"}' \
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/user/106798',
    method: 'PUT',
    body: JSON.stringify({"fullName":"Bar Foonum", "department": "sales"})
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

{
  "email": "foo@barnum.com",
  "tenantId": 1234,
  "userId": 106798,
  "role": 1,
  "softwareLevel": "prod",
  "hasGooglePermission": false,
  "companyName": "Tenant",
  "firstName": "Bar",
  "lastName": " Foonum",
  "title": null,
  "phone": null,
  "dialerPhone": null,
  "profilePicture": null,
  "signature": null,
  "fullName": "Bar Foonum",
  "usageJson": {},
  "settings": {},
  "passwordAuth": true,
  "googleAppAuth": false,
  "googleAppBasicAuth": false,
  "samlAuth": false,
  "authType": 1,
  "requireApproval": false,
  "tenantGoogleAppAuth": false,
  "tenantPasswordAuth": true,
  "tenantGoogleAppBasicAuth": false,
  "tenantSamlAuth": false,
  "tenantAuthType": 17,
  "tenantDomainHash": "sadfafafawfawfsafdccceceacsddascac",
  "includeAccountDescendantsMode": false,
  "emailTech": "Gmail",
  "accessLevel": 0,
  "hasOauthToken": false,
  "tenantAuthScope": 0,
  "tenantSfdcInstanceUrl": "https://test.salesforce.com",
  "department": "sales",
  "supportToolHash": "asdf23fj3j324kjf23kj23adfadsf88dsaf8saf8sadf8",
  "hasEmailSync": true,
  "isFastSyncEnabled": true,
  "oppPipelineDateField": "{Opportunity}.closedDate",
  "features": {
    "Advertising": 8,
    "Personalization": 8,
    "Automation": 8,
    "SelfServeAdvertising": 8,
    "SalesforceLite": 0,
    "DataImport": 8,
    "DemandbaseIntent": 8,
    "Database": 8,
    "Aggregates": 0,
    "Audience": 8,
    "ActivityLogging": 8,
    "Intent Data": 0,
    "Slack": 0,
    "ServiceAccount": 8,
    "AccountConnector": 8,
    "AccountConnectorSimpleSync": 8,
    "Dash": 8,
    "PardotSFDCAuth": 0
  },
  "permissionSetIds": [],
  "tenantDatabaseHost": "platform-tenant01-rds-rw-us-east-1.stg.demandbase.com",
  "tenantDbName": "c1234_tenant",
  "currentDataConnectionMode": "CONNECTED_CRM"
}

The Update User endpoint updates the full name and department for a Demandbase One user

HTTP Request

PUT https://gateway.demandbase.com/api/v1/user/{userId}

Request Body

Parameter	Type	Description
fullName	string	Display name
department	string	Department

Responses

Updated user json

Invalid request

Server error occurred

PUT /user/{userId}/role/{roleId}

curl \
  -G "https://gateway.demandbase.com/api/v1/user/106798/role/3" \
  -X PUT
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/user/106798/role/3',
    method: 'PUT',
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

{
  "tenant": {
    "id": 1234,
    "name": "tenant",
    "dbName": "c1234_tenant",
    "createdDate": "2020-08-07T19:37:07Z",
    "domain": "yourdomain.com",
    "emailTech": "Gmail",
    "settings": {
      "demo": true,
      "sku": {
        "Dash": true
      },
      "bomboraUniverseListId": 5262,
      "preferredEngagementMinsSource": "Marketo",
      "taskCategoryField": "Type",
      "isBomboraPaidCustomer": true,
      "csActivityLevelUpload": {
        "uploadHubSpot": true,
        "uploadCampaign": true,
        "uploadOutreach": true,
        "uploadSalesloft": true
      },
      "serviceLevel": "Executive",
      "scout": {
        "profileTwitterField": "_createdbyexternalparty_value",
        "showSidePanelTab": true,
        "showRunPlay": true,
        "profileLinkedinField": "_ownerid_value",
        "profilePictureField": "_createdby_value",
        "showCommunicationHistory": true
      },
      "bomboraUniverseListLabel": "+test",
      "fiscalYearStartMonth": 2,
      "isEmailServiceAccountFeatureEnabled": true,
      "isShowingOpportunityScreen": true,
      "accountListsForOwners": true
    },
    "domainHash": "sadfafafawfawfsafdccceceacsddascac",
    "softwareLevel": "prod",
    "passwordSecurity": "NORMAL",
    "passwordAuth": true,
    "salesforceAuth": true,
    "googleAppAuth": false,
    "googleAppBasicAuth": false,
    "samlAuth": false,
    "emailLockType": 2,
    "emailLockUsers": [],
    "activityUploadLevel": 512,
    "exchangeServerUrl": null,
    "dbServerIndex": 0,
    "maintenanceMode": 0,
    "authScope": 0,
    "tenancy": "D",
    "serviceAccountEnabled": true,
    "connectionModeOverwrite": "CONNECTED_CRM",
    "salesforceAccountId": null,
    "licenseAgreementRequired": false,
    "demo": false
  },
  "user": {
    "id": 106798,
    "email": "foo@barnum.com",
    "fullName": "Foo Barnum",
    "createdAt": "2021-03-11T02:10:36Z",
    "validatedAt": null,
    "passwordExpiresAt": "1970-01-01T00:00:00Z",
    "firstName": null,
    "lastName": null,
    "title": null,
    "phone": null,
    "dialerPhone": null,
    "profilePicture": null,
    "signature": null,
    "department": "marketing",
    "settings": {},
    "hasGooglePermission": false,
    "emailTrustUsers": [
      -1
    ],
    "passwordAuth": true,
    "salesforceAuth": false,
    "googleAppAuth": false,
    "googleAppBasicAuth": false,
    "samlAuth": false,
    "createdBy": "vramesh@demandbase.com",
    "expired": false,
    "requireApproval": false
  },
  "role": 3,
  "priority": 1,
  "accessLevel": 0,
  "settings": {},
  "id": 107441
}

The Update Role endpoint updates the role for a Demandbase One user

HTTP Request

PUT https://gateway.demandbase.com/api/v1/user/{userId}/role/{roleId}

Path Parameters

Parameter	Type	Description
userId	int	User id
roleId	int	User role (1 = general, 3 = admin)

Responses

Updated user json

Invalid role

Invalid user id

Server error occurred

DELETE /user/{email}

curl \
  -G "https://gateway.demandbase.com/api/v1/user/foo@barnum.com" \
  -X DELETE
  -H "Authorization: Bearer v334asfsdfo3241ERqwefe"

var request = require('request');

request({
  headers: {
    'Authorization': 'Bearer v334asfsdfo3241ERqwefe',
    'Content-Type': 'application/json'
  },
    uri: 'https://gateway.demandbase.com/api/v1/user/foo@barnum.com',
    method: 'DELETE',
  }, function (err, res, body) {
    var pJSON = JSON.parse(body);
    console.log(pJSON)
})

The Delete User endpoint deletes a given Demandbase One user

HTTP Request

DELETE https://gateway.demandbase.com/api/v1/user/{email}

Path Parameters

Parameter	Type	Description
email	string	User email

Responses

No content

Invalid user

Server error occurred

API Schema Definitions

Field: Object

name: string

Name of the field - pass this to the endpoints that expect a field list.

label: string

Human-friendly label for the field

dataType: string

Data type of the field

pickListValues: object

cardinality: number

status: string

Is this a hidden, normal, or preferred field in the Demandbase web application?

Filter: Object

field: string

operator: string

Possible Values: Equals, Does Not Equal, Contains, Does Not Contain, Begins With, Does Not Begin With, Ends With, Does Not End With, Greater Than, Greater Than or Equal To, Less Than, Less Than or Equal To, Between

values: string[], string

Example Filter {"field": "{Account}.sfdcId", "operator": "Equals", "values": ["0011a00000DpxW3AAJ"]}