General options for sessions are specified as body parameters when initiating a session.

Save Session

By default, all sessions and related data (authentication, transfer data, etc.) persist for 72 hours before they are permanently deleted per our TTL policies. In order to persist a session beyond that timeframe, set the save_session flag to true.

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",
    }
  ],
  // We have the save_session flag enabled persist the authentication of the session for longer than 72 hours.
  "save_session": true
}
'

Sync

The sync flag tells Endgrate to return only new, updated, or deleted data when pulling in data. Endgrate will cache previously pulled data, and check against that cache when returning data to you. On the first pull, the cache will be empty, so all data will be returned to you. Subsequent pulls will check against and update the cache.

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",
    }
  ],
  // We have the sync flag enabled to only return new/updated/deleted data when pulling in data.
  "sync": true
}
'

Passthrough Fields (Custom Fields)

Passthrough fields are fields for the integration provider that you don't have defined in your standardized schema. A typical use case is to pull in the custom fields that your end users have set up for an integration provider. To enable this feature, set the passthrough_fields flag to true.

Endgrate will first handle the data standardization by mapping fields in your standardized schema to fields for the integration provider. The passthrough fields are the remaining unmapped fields for the integration provider.

When pulling in data, the data will contain the passthrough fields in addition to fields conforming to your standardized schema.

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": [
    // Here, our standardized schema has two fields: first_name and last_name.
    {
    	"endgrate_type": "crm-contact",
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        }
    }
  ],
  // We have the passthrough_fields flag enabled to pull in the passthrough fields.
  "passthrough_fields": true
}
'

{
  // This is data conforming to our standardized schema.
  "first_name": "Bob",
  "last_name": "Smith",

  // These are the passthrough fields from the integration provider.
  "my_custom_field": 123
}

You can get the format of the passthrough fields for a schema through the GET api/session/configuration endpoint, which we'll review later.

Passthrough Schemas (Custom Objects)

Passthrough schemas are schemas for the integration provider that you don't have specified in your session initiate request. A typical use case is to pull in the custom objects that your end users have set up for an integration provider. To enable this feature, set the passthrough_schemas flag to true.

For passthrough schemas, the endgrate_type of the schema is not standard. Rather, it is the name of the custom object that your end user set up. In addition, there is no standardized schema. Rather, all fields are passthrough fields. You can get the endgrate_types of passthrough schemas as well as the format of the passthrough fields for them through the GET api/session/configuration endpoint, which we'll review later.

Furthermore, if you specify passthrough schemas but set the schema_selectionflag to falsethen every custom and Endgrate schema for the current provider will automatically be selected as a passthrough schema.

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",
    }
  ],
  // We have the passthrough_schemas flag enabled to pull in the passthrough schemas (custom objects).
  "passthrough_schemas": true
}
'