Quick Start

Suggest Edits

Our quick start guide is a quick and easy way to get familiarized with Endgrate's platform.

In this guide, we'll set up a full integration workflow example for pulling and pushing CRM contact and CRM company data.

🚧

Note

Make sure you've read our Documentation Overview and Core Concepts before diving in.

Setup

Retrieve your API key from the settings page of your dashboard. This is what Endgrate uses to authenticate your requests to the API.

Initiate Session

🚧

Note

In the code examples below, you'll see some values in ALL CAPS, such as API_KEY, SESSION_ID, and TRANSFER_ID. These are placeholders and must be replaced with valid values.

First, initiate a session using the POST api/session/initiate endpoint. Specify the schemas you want to work with. As discussed previously, in this quick start example it will be CRM contact and CRM company data.

curl --request POST \
     --url https://endgrate.com/api/session/initiate \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "schema": [
    {
    	"endgrate_type": "crm-contact"
    },
    {
    	"endgrate_type": "crm-company"
    }
  ]
}
'

import requests

url = "https://endgrate.com/api/session/initiate"

payload = { "schema": [{ "endgrate_type": "crm-contact" }, { "endgrate_type": "crm-company" }] }
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer API_KEY"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer API_KEY'
  },
  body: JSON.stringify({schema: [{endgrate_type: 'crm-contact'}, {endgrate_type: 'crm-company'}]})
};

fetch('https://endgrate.com/api/session/initiate', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

You could also specify a category that adds all Endgrate types of the category.

curl --request POST \
     --url https://endgrate.com/api/session/initiate \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "category": "crm"
}
'

import requests

url = "https://endgrate.com/api/session/initiate"

payload = { "category": "crm" }
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer API_KEY"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer API_KEY'
  },
  body: JSON.stringify({category: "crm"})
};

fetch('https://endgrate.com/api/session/initiate', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

📘

Note

You can use category and schema at the same time. When a category is defined, it add all schemas from the catagory that are not already defined. This is usefull if you want to define more that just an endgrate_type for a schema in your integration.

You'll receive a session_id in return:

{
  "success": true,
  "session_id": "SESSION_ID"
}

📘

Note

If you just need to pull in or just need to push out data, feel free to use the POST api/pull/initiate and POST api/push/initiate endpoints respectively — they generally take in the same parameters.

📘

Note

For simplicity, we used Endgrate's built-in standardized schemas. Learn more on schemas, including how to define your own custom ones, here.

📘

Note

For simplicity, we did not use any of Endgrate's customization options. Check out the API reference for a full list of parameters and feature explanations.

Redirect End User

Then, redirect your end user to the GET /session page in a new tab or pop-up window so that they can choose an integration provider, authenticate, and configure the session.

<a href="https://endgrate.com/session?session_id=SESSION_ID" target="_blank">

Trigger Transfers

Lastly, you can trigger transfers using the POST /api/pull/transfer endpoint and the POST /api/push/transfer endpoint.

Pull Data

To pull data, first trigger the transfer for a given schema.

curl --request POST \
     --url https://endgrate.com/api/pull/transfer \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "session_id": "SESSION_ID",
  "endgrate_type": "crm-contact",
  "synchronous": true
}
'

import requests

url = "https://endgrate.com/api/pull/transfer"

payload = {
    "session_id": "SESSION_ID",
    "endgrate_type": "crm-contact",
    "synchronous": True
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer API_KEY"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer API_KEY'
  },
  body: JSON.stringify({
    session_id: 'SESSION_ID',
    endgrate_type: 'crm-contact',
    synchronous: true
  })
};

fetch('https://endgrate.com/api/pull/transfer', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

You'll receive a transfer_id in return:

{
  "success": true,
  "transfer_id": "TRANSFER_ID",
  "statistics": "https://endgrate.com/statistics?transfer_id=TRANSFER_ID"
}

Then, query for data using the GET /api/pull/data endpoint:

curl --request GET \
     --url https://endgrate.com/api/pull/data?endgrate_type=crm-contact&transfer_id=TRANSFER_ID \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_KEY'

import requests

url = "https://endgrate.com/api/pull/data?endgrate_type=crm-contact&transfer_id=TRANSFER_ID"

headers = {
    "accept": "application/json",
    "authorization": "Bearer API_KEY"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {accept: 'application/json', authorization: 'Bearer API_KEY'}
};

fetch('https://endgrate.com/api/pull/data?endgrate_type=crm-contact&transfer_id=TRANSFER_ID', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

The data you'll receive will conform exactly to the schema specified in the request.

📘

Note

For simplicity, we used the synchronous flag so that immediately after our call to /api/pull/transfer returned, we could query for the completed transfer data. In most production use cases with a large amount of data being transferred, we recommend either:

  1. Periodically polling the api/pull/data endpoint until the transfer is completed, or
  2. Using webhooks (having Endgrate notify you when the transfer is complete so you can then call api/pull/data, or having Endgrate directly send transfer data to you).

Push Data

To push data, first batch your data into groups of 250 objects, and make sure the individual objects conform to the given schema.

Then, trigger a transfer for each batch.

📘

Note

For simplicity, we are only sending company_name and website. The crm-company standardized schema contains many other fields you can use. A reference is available here.

curl --request POST \
     --url https://endgrate.com/api/push/transfer \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "session_id": "SESSION_ID",
  "endgrate_type": "crm-company",
  "transfer_data": [
    {
      "data": {
        "company_name": "Endgrate",
        "website": "https://endgrate.com"
      }
    }
  ]
}
'

import requests

url = "https://endgrate.com/api/push/transfer"

payload = {
    "session_id": "SESSION_ID",
    "endgrate_type": "crm-company",
    "transfer_data": [{ "data": {
                "company_name": "Endgrate",
                "website": "https://endgrate.com"
            } }]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer API_KEY"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer API_KEY'
  },
  body: JSON.stringify({
    session_id: 'SESSION_ID',
    endgrate_type: 'crm-company',
    transfer_data: [{data: {company_name: 'Endgrate', website: 'https://endgrate.com'}}]
  })
};

fetch('https://endgrate.com/api/push/transfer', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Delete Session

🚧

Note

If you are on the Free Plan, you MUST delete your sessions after use BEFORE creating a new one!

If desired, you can delete sessions and all of their accompanying data using the POST /api/session/delete endpoint.

curl --request POST \
     --url https://endgrate.com/api/session/delete \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "session_id": "SESSION_ID"
}
'

import requests

url = "https://endgrate.com/api/session/delete"

payload = { "session_id": "SESSION_ID" }
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer API_KEY"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer API_KEY'
  },
  body: JSON.stringify({session_id: 'SESSION_ID'})
};

fetch('https://endgrate.com/api/session/delete', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Updated 10 days ago