Trigger Transfer

To pull data, first initiate a transfer using the POST api/pull/transfer endpoint.

Specify the session_id of the session you are using, and the endgrate_type you are pulling in.

Associations

Endgrate supports pulling in associated resource data. To do so, specify desired associations keyed by endgrate_type in the associations attribute. Note that these endgrate_types must exist in your session.

curl --request POST \
     --url https://endgrate.com/api/pull/transfer \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "associations": {
    "crm-company": true // Here, I am specifying for Endgrate to get the associated CRM companies for the resource.
  },
  "endgrate_type": "crm-contact",
  "session_id": "6566e85e7cf20dca9cef0c0a"
}
'

Pull Parameters

To filter the data that gets returned from a pull transfer, you can specify params in the request. When defining params, you can filter for fields with either a single value or a list of multiple values. Nested object filtering is also supported by default.

curl --request POST \
     --url https://endgrate.com/api/pull/transfer \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "associations": {
    "crm-company": true
  },
  "params": {
    "first_name": ["John","Jane"],
    "last_name": "Doe",
    "email": {"type": "WORK"}
  },
  "endgrate_type": "crm-contact",
  "session_id": "6566e85e7cf20dca9cef0c0a",
  "data_webhook": {
    "url": "https://postexample.com",
    "metadata": {
      "id": "1",
    }
  },
  "completed_webhook": {
    "url": "https://postexample.com",
    "metadata": {
      "id": "1",
    }
  },
  "error_webhook": {
    "url": "https://postexample.com",
    "metadata": {
      "id": "1",
    }
  },
}
'

Ranges

To filter the data by a range of values, when specifying params add __range to the end of the field, it will accept a list of the minimum and maximum inclusive bounds. Ranges support the types number,date,time, and datetime. You can also filter multiple ranges by instead defining params as a list of ranges.

{
  "params": {
    	"transaction_date__range":["2024-01-01","2024-02-01"],
      "due_date__range":[["2024-01-01","2024-02-01"],["2024-03-01","2024-04-01"]]
  }
}

Get Data

To get the data, call the GET api/pull/data endpoint once the transfer is completed. You can also choose to get the data directly sent via the transfer data webhook by specifying it duringapi/pull/transfer. For more information on the data webhook visit webhook options.

For all of the pulled resources, you'll receive the id of the resource and the data returned by the integration provider converted into your standardized schema format. If associations were requested, you'll get them in the associations attribute keyed by endgrate_type.

{
  "success": true,
  "meta": {
    "count": 2,
    "previous": {
      "offset": 100,
      "link": "https://endgrate.com/api/pull/data?transfer_id=abcabc123123abcabc123123&limit=100&offset=100"
    },
    "next": {
      "offset": 300,
      "link": "https://endgrate.com/api/pull/data?transfer_id=abcabc123123abcabc123123&limit=100&offset=300"
    }
  },
  "transfer_data": [
  {
    // This is a HubSpot contact ID.
    "id": "HSContact1",
    // This is the contact data from HubSpot conforming to the standardized schema I set up in the session.
    "data": {
      "first_name": "HubSpot",
      "last_name": "Hank"
    },
    // These are the associated resources that I requested.
    "associations": {
      "crm-company": [
        {
          // This is the associated HubSpot company ID.
          "id": "HSCompany1",
          // This is the contact data from HubSpot conforming to the standardized schema I set up in the session.
          "data": {
            "name": "HubSpot"
          }
        },
        {
          "id": "HSCompany2",
          "data": {
            "name": "Acme Corporation"
          }
        }
      ]
    }
  },
  // This is another pulled contact from HubSpot
  {
    "id": "HSContact2",
    "data": {
      "first_name": "Cindy",
      "last_name": "John"
    },
    "associations": {
      "crm-company": []
    }
  }
],
  // whether any errors occurred during this transfer
  "transfer_errors": false
}

Get Completed Message

To get a completion notice sent to your API you can specify the completed_webhook when initiating a pull transfer. A completion notice will automatically get sent whenever all the data finishes transferring. For more information on the completed webhook visit webhook options.

Get Error Message

To get error messages sent to your API you can specify the error_webhook when initiating a pull transfer. Whenever an error occurs during the transfer process, we will automatically post data to the webhook you specify with your metadata. For more information on the error webhook visit webhook options.