Multitype Schemas

Suggest Edits

In some cases you may want to make one custom schema that is representative of multiple different types of data. In this case you would not want to use an endgrate_type.

In this guide, we'll set up a full integration workflow example for pulling and pushing Contact data using a fully custom schema.

The main change in this example from the Quick Start guide is using the specified title of your custom JSON schema in place of the endgrate_type in subsequent API calls.

Initiate Session without an endgrate_type

🚧

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 custom schemas you want to work with. In this example it will be Contact 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": [
    {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string",
          "title": "First Name"
        },
        "last_name": {
          "type": "string",
          "title": "Last Name"
        },
        "email": {
          "type": "string",
          "format": "email",
          "title": "Email"
        }
      },
      "required": [
        "email"
      ],
      "title": "Contact"
    }
  ],
  "resource_selection": true
}
'

import requests

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

payload = {
    "schema": [
        {
            "properties": {
                "first_name": {
                    "type": "string",
                    "title": "First Name"
                },
                "last_name": {
                    "type": "string",
                    "title": "Last Name"
                },
                "email": {
                    "type": "string",
                    "format": "email",
                    "title": "Email"
                }
            },
            "type": "object",
            "required": ["email"],
            "title": "Contact"
        }
    ],
    "resource_selection": 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({
    schema: [
      {
        properties: {
          first_name: {type: 'string', title: 'First Name'},
          last_name: {type: 'string', title: 'Last Name'},
          email: {type: 'string', format: 'email', title: 'Email'}
        },
        type: 'object',
        required: ['email'],
        title: 'Contact'
      }
    ],
    resource_selection: true
  })
};

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

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 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 endpoint 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 without an endgrate_type

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

Pull Data without an endgrate_type

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": "Contact",
  "synchronous": true
}
'

import requests

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

payload = {
    "endgrate_type": "Contact",
    "session_id": "SESSION_ID",
    "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({endgrate_type: 'Contact', session_id: 'SESSION_ID', 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=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=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=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 without an endgrate_type

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.

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 '
{
  "endgrate_type": "Contact",
  "session_id": "SESSION_ID",
  "transfer_data": [
    {
      "data": {
        "first_name": "John",
        "last_name": "Smith",
        "email": "[email protected]"
      }
    }
  ]
}
'

import requests

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

payload = {
    "endgrate_type": "Contact",
    "session_id": "SESSION_ID",
    "transfer_data": [{ "data": {
                "first_name": "John",
                "last_name": "Smith",
                "email": "[email protected]"
            } }]
}
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({
    endgrate_type: 'Contact',
    session_id: 'SESSION_ID',
    transfer_data: [
      {
        data: {first_name: 'John', last_name: 'Smith', email: '[email protected]'}
      }
    ]
  })
};

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

Updated about 2 months ago