POST - Export profile data

Profiles centralize data and events from multiple sources (Apps, Websites, APIs) in a single place based on the Custom ID.

The Profile API allows you to export profiles data. Use this endpoint to:

Export profile native attributes
Export profile custom attributes
Export profile identifiers
Export profile events

API Description

This API schema is available in the OpenAPI 3.1 format: View it online.

Lookback

Some kind of exports are logs of detailed events that happened. Those raw events are not kept forever and will stop being available to export after a while: this is documented in the "Lookback" duration for each event kind. Providing a from parameter older than the lookback period will result in an error.

Exports that represent a snapshot of data (such as Profile Attributes) do not have this limitation.

Route

The Profile API exposes a POST endpoint that allows to create an export request:

https://api.batch.com/2.3/profiles/export

Headers and authentication

See Overview → Using Project APIs.

Profile Attributes

Use this to export custom and native attributes as well as the identifiers of your profiles.

Request structure

The body of the request must contain a valid JSON payload describing the export request to be executed.

Here is a how a complete JSON payload looks like:

{
    "export_type": "ATTRIBUTES",
    "attributes": [
        "$email_address",
        "$email_marketing",
        "$phone_number",
        "$sms_marketing",
        "$region",
        "$timezone",
        "$language",
        "first_name",
        "is_premium"
    ],
    "identifiers": [
        "custom_id",
        "installation_ids"
    ]
}

Let's see the parameters in detail.

Id	Description
`export_type`	string - Required Type of the export. Must be `ATTRIBUTES`. E.g.`{"export_type":"ATTRIBUTES"}`
`attributes`	string - Optional Profile attributes to be exported. You have to specify the attribute you want to be exported. Any value that does not start with a `$` will be interpreted as a custom attribute. You can find a list of available native attributes on the OpenAPI documentation. E.g.`{"attributes":["$region","$timezone","$language","first_name","is_premium"]}`
`identifiers`	string - Optional Profile identifiers to be exported. You have to specify the identifier you want to be exported. E.g.`{"identifiers":["custom_id"]}`

You must specify at least one of attributes, identifiers or both in your export request.

Profile Events

Use this to export events associated with your profiles.

Lookback

90 days

Request structure

The body of the request must contain a valid JSON payload describing the export request to be executed.

Here is a how a complete JSON payload looks like:

{
    "export_type": "EVENTS",
    "from": "2024-01-01T00:00:00Z",
    "to": "now",
    "events": [
        "email_bounced",
        "email_click",
        "email_delivered",
        "email_unsubscribed"
    ],
    "identifiers": [
        "custom_id"
    ]
}

Id	Description
`export_type`	string - Required Type of the export. Must be `EVENTS`. E.g.`{"export_type":"EVENTS"}`
`from`	string - Required UTC date in a RFC 3339 format. Must not be older than the lookback period. E.g.`"2024-01-01T00:00:00Z"`
`to`	string - Required 'now' or UTC date in a RFC 3339 format E.g.`"now"`
`events`	string - Optional Events associated with a profile to be exported. You have to specify the events you want to be exported. You can find a list of available events on the OpenAPI documentation. E.g.`{"events":["email_bounced","email_click","email_delivered"]}`
`identifiers`	string - Optional Profile identifiers to be exported. You have to specify the identifier you want to be exported. E.g.`{"identifiers":["custom_id"]}`

Profile Reachability Events

Use this to export the reachability events of your profiles.

Lookback

Reachability events are available since October 10, 2024. No events are available prior to this date. Lookback period will be 90 days.

Request structure

The body of the request must contain a valid JSON payload describing the export request to be executed.

Here is a how a complete JSON payload looks like:

{
  "export_type": "REACHABILITY",
  "from": "2024-01-01T00:00:00Z",
  "to": "now",
  "channels": [
    "push",
    "email",
    "sms"
  ],
  "identifiers": [
    "custom_id",
    "installation_id"
  ]
}

Id	Description
`export_type`	string - Required Type of the export. Must be `REACHABILITY`. E.g.`{"export_type":"REACHABILITY"}`
`from`	string - Required UTC date in a RFC 3339 format. Must not be older than the lookback period. E.g.`"2024-01-01T00:00:00Z"`
`to`	string - Required 'now' or UTC date in a RFC 3339 format E.g.`"now"`
`identifiers`	string - Optional Profile identifiers to be exported. You have to specify the identifier you want to be exported. `profile_id` will always be exported, `installation_id` is only available on PUSH channels. E.g.`{"identifiers":["custom_id","installation_id"]}`
`channels`	string - Optional Channels to export events for. You need to specify the channels for which events will be exported. E.g.`{"channels":["push","email","sms"]}`

Export file structure

The export will contain a list of reachability events. Each event is composed of an event object and an identifiers object.

Id	Description
`event`	object - Required Representation of a reachability event object. See: Event Object .
`identifiers`	object - Required Representation of an identifiers object. See Identifiers Object .

Event Object

Representation of an reachability event object. it also describe a part of the profile state at the time of the event.

Id	Description
`channel`	string - Required Channel where the event happened. E.g.`{"channel":["SMS","EMAIL","PUSH"]}`
`id`	string - Required Unique identifier of the event. E.g.`{"id":"6156b060574cb223e8c4ed47c5df1855"}`
`timestamp`	string - Required UTC date in a RFC 3339 format. E.g.`{"timestamp":"2024-01-01T00:00:00Z"}`
`reasons`	array - Required Reasons why an event has been triggered. See: Event Reasons . E.g.`{"reasons":["SUBSCRIBED_TO_SMS_MARKETING","PHONE_NUMBER_ADDED"]}`
`has_phone_number`	boolean - Optional Only for SMS channel, it means the profile has a phone number. E.g.`{"has_phone_number":true}`
`has_email_address`	boolean - Optional Profile's marketing email subscription. E.g.`{"has_email_address":true}`
`sms_marketing`	string - Optional Profile's marketing SMS subscription. E.g.`{"sms_marketing":"subscribed"}`
`email_marketing`	string - Optional Profile's marketing emails subscription. E.g.`{"email_marketing":"subscribed"}`
`is_optin`	boolean - Optional Installation's notification system opt-in state. E.g.`{"is_optin":false}`
`platform`	string - Optional Platform of the installation (iOS/Android/Webpush). Only available on PUSH channels. E.g.`{"platform":"iOS"}`

Identifiers object

Represents the identifiers of the profile concerned by the event.

Id	Description
`profile_id`	string - Required Unique identifier of the profile. E.g.`{"profile_id":"profile_063kxgw384nn7k3wxgsa0xfbd0pgmd9v"}`
`custom_id`	string - Optional Custom identifier of the profile. E.g.`{"custom_id":"User1"}`
`installation_id`	string - Optional Installation identifier of the profile. Only available on PUSH channels. E.g.`{"installation_id":"828A7D76-3D5E-49DC-A863-2465070184C9"}`

Event reasons

Exhaustive list of reasons for the event.

SUBSCRIBED_TO_SMS_MARKETING: The profile subscribed to SMS marketing.
UNSUBSCRIBED_FROM_SMS_MARKETING: The profile unsubscribed from SMS marketing.
PHONE_NUMBER_ADDED: The profile added a phone number.
PHONE_NUMBER_REMOVED: The profile removed a phone number.
PHONE_NUMBER_UPDATED: The profile updated a phone number.
SUBSCRIBED_TO_EMAIL_MARKETING: The profile subscribed to email marketing.
UNSUBSCRIBED_FROM_EMAIL_MARKETING: The profile unsubscribed from email marketing.
EMAIL_ADDRESS_ADDED: The profile added an email address.
EMAIL_ADDRESS_REMOVED: The profile removed an email address.
EMAIL_ADDRESS_UPDATED: The profile updated an email address.
SUBSCRIBED_TO_PUSH: The profile got an optin install.
UNSUBSCRIBED_FROM_PUSH: The profile unsubscribed from push notifications.
PUSH_TOKEN_ADDED: The profile added a push token.

Export file sample

This is a sample of the content of the export file you will receive.

Example

[
  {
    "event": {
      "channel": "SMS",
      "id": "6156b060574cb223e8c4ed47c5df1855",
      "timestamp": "2024-01-01T00:00:00Z",
      "reasons": [
        "PHONE_NUMBER_ADDED",
        "SUBSCRIBED_TO_SMS_MARKETING"
      ],
      "has_phone_number": true,
      "sms_marketing": "subscribed"
    },
    "identifiers": {
      "profile_id": "profile_063kxgw384nn7k3wxgsa0xfbd0pgmd9v",
      "custom_id": "User1"
    }
  },
  {
    "event": {
      "channel": "EMAIL",
      "id": "6156b060574cb223e8c4ed47c5df1855",
      "timestamp": "2024-01-01T00:00:00Z",
      "reasons": [
        "SUBSCRIBED_TO_EMAIL_MARKETING"
      ],
      "has_email_address": true,
      "email_marketing": "subscribed"
    },
    "identifiers": {
      "profile_id": "profile_063kxgw384nn7k3wxgsa0xfbd0pgmd9v",
      "custom_id": "User1"
    }
  },
  {
    "event": {
      "channel": "PUSH",
      "id": "6156b060574cb223e8c4ed47c5df1856",
      "timestamp": "2024-01-01T00:00:00Z",
      "reasons": [
        "SUBSCRIBED_TO_PUSH"
      ],
      "is_optin": true,
      "platform": "iOS"
    },
    "identifiers": {
      "profile_id": "profile_063kxgw384nn7k3wxgsa0xfbd0pgmd9v",
      "custom_id": "User1",
      "installation_id": "828A7D76-3D5E-49DC-A863-2465070184C9"
    }
  }
]

Responses

Success

If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and an export ID. This ID can be used to get status information about your export request using the Project Export API endpoints.

{
    "id": "export_nvctr8tgdjf7bppacxxt2aeemnjehfmw"
}

Failure

If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at support@batch.com if you need further support.

See the list of potential failures in the specification.

Documentation > API > Profile API

POST - Export profile data

API Description

Lookback

Route

Headers and authentication

Profile Attributes

Request structure

Profile Events

Lookback

Request structure

Profile Reachability Events

Lookback

Request structure

Export file structure

Event Object

Identifiers object

Event reasons

Export file sample

Example

Responses

Success

Failure