Introduction
This site provides documentation, examples and guides for the public API of the APSIS One platform.
Getting started
Start by reading about reaching our public API from your region. To be able to call our API you also need to authenticate. Finally familiarize yourself with the important concepts regarding the limits.
Managing your APSIS One data
Once you know how to call the API you can start building your integration. The sidebar provides documentation to all the currently supported endpoints under the API reference section.
The endpoints inside the Definitions and Folders categories let you interact with your account configuration.
Different aspects of individual profile management are supported by the APIs inside the Profiles, Attributes, tags and events, Segments and Consents categories. The Profile import and Profile export categories provide means of bulk profile management.
Finally, the endpoints to manage your activities are placed inside the Email, SMS, Forms & Pages, Website and Marketing Automation categories.
Guides
This site also provides the guides for common use cases. You can find them in the Guides section on the sidebar.
Knowledge base
See our knowledge base for more information about the APSIS One API including more detailed getting started tutorials, pricing and many guides related to profile management.
What's new
Our CHANGELOG provides information about the new API features as well as the updates to the existing API functionality.
We often preview the upcoming endpoints in the In development section of this site. This gives you some insight into the future of APSIS One API. Note that these features are likely to change while we're working on them.
Have questions?Contact support@efficy.com to learn more
Configuring your integrations
APSIS One uses different URLs in Europe and Asia. The same applies to APSIS One API.
Note that the code samples on the endpoint pages refer to the server in Europe.
Europe
If you are a customer from Europe and access Apsis One via https://app.apsis.one/ then you should use https://api.apsis.one/ base URL when building your integrations.
Asia
If you are in Asia and use https://apac.apsis.one/ to login to APSIS One then build your integrations with https://api-apac.apsis.one/ base URL.
✉️ Have questions?Contact support@efficy.com to learn more
Introduction
APSIS One API uses Bearer Authentication as designed in RFC 6750. This guide will teach you how to authenticate your integration with our API.
Create an API key
Create an API key in your APSIS One account settings. You can have multiple API keys to better manage your integrations with APSIS One API. Once you've deleted an API key in APSIS One account settings, APSIS One API will no longer accept it.
Add the API key to your integration settings
Store client ID and secret key in your integration settings. These are in fact the credentials to APSIS One API and thus it's sensitive data so it's best to encrypt them at rest and in transfer.
Obtain an access token
Call our token endpoint providing your client ID and secret key in the request body:
curl --location --request POST 'https://api.apsis.one/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "client_credentials",
"client_id": "b49b39a0-82a1-11ec-8017-5d554e8551d6",
"client_secret": "4n0TpfkaedYOkIljy0mtAs4Y2r2qR5XGrBhpt20Cf3LYaE45piAPunlVAq4jbJBV"
}'
The response will contain your access token along with the scheme and expiration period:
{
"access_token": "eyJhbGciOiJSUz...",
"expires_in": 86400,
"token_type": "Bearer"
}
Cache the access token
Store the access_token value in your integration cache and reuse it during the time when it remains valid to avoid redundant calls to the token endpoint.
Currently our access tokens are valid for up to 24 hours. In your client, decode the access_token and retrieve the expiration time from the exp claim. When the token is close to expiry, request it again using the token endpoint.
The deprecated expires_in response property is provided for backwards compatibility. The use of this property is discouraged.
To encourage proper authentication token caching, the token endpoint is rate limited more strictly. When this limit is reached, HTTP 429 Too Many Requests is returned. When this happens, retry the call with exponential back-off.
Making calls to APSIS One API
When making calls to other endpoints of this API, provide the cached authentication token as Authorization: Bearer <access token> header. Here's an example:
curl --location --request GET 'https://api.apsis.one/audience/keyspaces' \
--header 'Authorization: Bearer eyJhbGciOiJSUz...'
Video guide
Here's a video guide that covers all of the above topics:
✉️ Have questions?Contact support@efficy.com to learn more
Introduction
This page provides the information about the current limits implemented in APSIS One API.
⚠️ Limits can changeFor the benefit of our customers, we are constantly improving the APSIS One platform stability and performance. Public API limits are one of the tools allowing us to achieve this goal. For that reason, we reserve the right to change the limits listed on this page without notice.
Rate limits
Rate limits are applied on the account level, independent of how many API keys you use.
- Most endpoints allow for up to 100 requests per second
- Authentication token request - up to 10 requests per minute
- Profile imports - up to 10 requests per minute
- Profile exports - up to 1 request per second
- Event exports - up to 1 request per minute
- Export downloads - up to 60 requests per minute
When you reach these limits, HTTP 429 Too Many Requests is returned.
Profile key based rate limits
Many features in APSIS One API allow single profile management. Some examples are Set attributes on a profile and Add events to a profile.
To protect the platform stability, increase the performance and encourage the proper use by combining multiple updates into a single request or choosing bulk features, like Request profile import (version 2), the following rate limits are put in place:
- Consecutive operations using the same profile key - up to 10 requests per second
Hints for mitigating these rate limits:
- Combine multiple profile attribute values into a single call when updating profiles using Set attributes on a profile
- Combine multiple profile events into a single call when using Add events to a profile
Size limits
Request body size is limited to 100 kB. Exceptions:
All lists accepted in the APSIS One API request bodies are limited based on the specific platform feature.
When you reach these limits, HTTP 413 Request Entity Too Large is returned.
Import limits
Imports have limits specific to the import files and frequency. Find details in the endpoint specification:
Export limits
Exports are limited in terms of the time frame as well as the data to include in the export file. Endpoint specification provides details:
✉️ Have questions?Contact support@efficy.com to learn more
Get keyspaces
Keyspaces
Keyspaces allow to identify the profiles using different profile keys. Specific operations can be performed on a profile identified through a particular keyspace.
Unique identifiers
Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace.
Profile access
Profile access via One API is allowed through the specified keyspaces only.
Keyspace permissions
Specific profile attribute and tag types can be read or written when a profile is identified through a profile key in a specific keyspace. To find out which, use the include_keyspace_permissions request parameter with Get attributes and Get all tags.
Subscription management
Subscriptions (consent) can only be managed via keyspaces with manage_subscriptions flag set to true.
Keyspaces supported by APSIS One API
Full support:
- Email Keyspace (
com.apsis1.keyspaces.email) uses email address as key and can be used to perform all profile operations. - SMS Keyspace (
com.apsis1.keyspaces.mobile) uses mobile phone number as key and can be used to perform all profile operations. - CRM Keyspace (
com.apsis1.keyspaces.crm-id) uses CRM-ID as key and can be used to perform all profile operations. Profile keys in this keyspace are initialized in a third party system.
Partial support:
- Export Keyspace (
com.apsis1.keyspaces.export) uses export keys to identify the profiles. These profile keys appear in the export files provided by this API and in the browser address bar when looking at a profile. This keyspace is read only and allows for reading profile attributes, tags, events and consents. It also supports locking, deleting and merging profiles.
Authorizations:
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/keyspaces \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.keyspaces.email",
- "name": "Email Keyspace",
- "description": "Email Keyspace",
- "manage_subscriptions": true
}
]
}Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/channels \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.channels.web",
- "name": "Web",
- "description": "Web Channel"
}
]
}Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/sections \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "name": "Default",
- "description": "My default section",
- "id": "1234"
}
]
}Get attributes
Gets all attributes within a specific section that are not hidden. Includes default and custom attributes.
When any e-commerce integration is connected to the specified section then also e-commerce attributes are returned.
In its requests and responses, APSIS One API accepts and returns version IDs and dates as strings. On the other hand, attribute value data types follow attribute types as described in this Help Center article.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_keyspace_permissions | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/attributes?include_keyspace_permissions=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.attributes.firstname",
- "name": "First name",
- "description": "First name",
- "versions": [
- {
- "id": "1234",
- "type": [
- "string"
], - "deprecated_at": "2017-07-21T17:32:28.761Z",
- "valid_from": "2017-07-21T17:32:28.761Z"
}
], - "keyspace_permissions": {
- "com.apsis1.keyspaces.email": [
- "read",
- "write"
], - "com.apsis1.keyspaces.sms": [
- "read"
]
}
}
]
}Get topics (version 2)
About consent
If a profile wants to receive communication regarding a specific topic over a specific channel (email or SMS), they must first give consent. The consent information is saved in APSIS One on a profile level along with the topic and the channel the consent is given for.
The following consent types are supported by APSIS One:
opt-in- profile permits communicationopt-out- profile forbids any communicationpending-opt-in- communication permission waits for the profile to confirm it (not supported by APSIS One API yet)confirmed-opt-in- profile permits communication which they also confirmed (not supported by APSIS One API yet)
Confirming the consent, also known as double opt-in, is usually done via a link in an email that is sent to the profile.
Get topics
Gets all topics from a specified section
More information
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/v2/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/topics \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "id": "12423",
- "name": "Shoes",
- "description": "New shoe offers",
- "folder_discriminator": "com.apsis1.folders.topic.promotions-pg5fiix3up"
}
]
}Get all tags
Get all tags defined within a specific section. Only tags that are not hidden are returned.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_keyspace_permissions | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/tags?include_keyspace_permissions=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "items": [
- {
- "discriminator": "usercreated.attributes.vip-npqjeo3mbb",
- "name": "VIP",
- "id": "1234",
- "keyspace_permissions": {
- "com.apsis1.keyspaces.email": [
- "read",
- "write"
], - "com.apsis1.keyspaces.sms": [
- "read"
]
}
}
]
}Create a single tag
Create a single tag
Creates a new tag with a provided name within a specific section
Limits
A maximum of 100 tags is allowed per section. The HTTP 400 Bad Request response status code is returned if a tag is attempted to be added over this limit.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
| name required | string [ 1 .. 255 ] characters Tag name |
Responses
Request samples
- Payload
- Curl
{- "name": "VIP"
}Response samples
- 201
- 400
- 404
- default
{- "discriminator": "usercreated.attributes.vip-npqjeo3mbb",
- "name": "VIP",
- "id": "1234"
}Get a single tag
Get a single tag within a specific section
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| tag_discriminator required | string Tag discriminator |
query Parameters
| include_keyspace_permissions | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/tags/%7Btag_discriminator%7D?include_keyspace_permissions=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "discriminator": "usercreated.attributes.vip-npqjeo3mbb",
- "name": "VIP",
- "id": "1234",
- "keyspace_permissions": {
- "com.apsis1.keyspaces.email": [
- "read",
- "write"
], - "com.apsis1.keyspaces.sms": [
- "read"
]
}
}Update a single tag
Updates a name of a single tag
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| tag_discriminator required | string Tag discriminator |
Request Body schema: application/jsonrequired
| name required | string [ 1 .. 255 ] characters Tag name |
Responses
Request samples
- Payload
- Curl
{- "name": "VIP"
}Response samples
- 200
- 400
- 404
- default
{- "discriminator": "usercreated.attributes.vip-npqjeo3mbb",
- "name": "VIP",
- "id": "1234"
}Get events
Get all events defined within a specific section that are not hidden.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_keyspace_permissions | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/events?include_keyspace_permissions=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.events.website.auto-collect.page-view",
- "name": "Auto Collect - Page view",
- "description": "Events collected on page view",
- "versions": [
- {
- "id": "1234",
- "type": [
- {
- "activityId": "string",
- "device": "string",
- "id": "string",
- "location": "string",
- "title": "string",
- "url": "string"
}
], - "deprecated_at": "2017-07-21T17:32:28.761Z",
- "valid_from": "2017-07-21T17:32:28.761Z"
}
], - "keyspace_permissions": {
- "com.apsis1.keyspaces.email": [
- "read",
- "write"
], - "com.apsis1.keyspaces.sms": [
- "read"
]
}
}
]
}Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/segments \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "items": [
- {
- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1",
- "name": "Segment1",
- "description": "Segment 1 description",
- "versions": [
- {
- "id": "14552",
- "query": "(section(1898).attribute(11737)) && (section(1898).attribute(11738)) && (section(1898).attribute(11739))\""
}
]
}
]
}Get segment
Get a single segment.
Authorizations:
path Parameters
| segment_discriminator required | string Example: usercreated.segments.europe-d8jye63u2y Segment discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/segments/usercreated.segments.europe-d8jye63u2y \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- default
{- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1",
- "name": "Segment1",
- "description": "Segment 1 description",
- "versions": [
- {
- "id": "14552",
- "query": "(section(1898).attribute(11737)) && (section(1898).attribute(11738)) && (section(1898).attribute(11739))\""
}
]
}Get segment version
Get specific segment version.
Authorizations:
path Parameters
| segment_discriminator required | string Example: usercreated.segments.europe-d8jye63u2y Segment discriminator |
| version_id required | string Resource version ID |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/segments/usercreated.segments.europe-d8jye63u2y/versions/%7Bversion_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "14552",
- "query": "(section(1898).attribute(11737)) && (section(1898).attribute(11738)) && (section(1898).attribute(11739))\""
}Get all topic folders
Gets the full folder tree for topics in a specific section. Use with Get topics (version 2) to match your topics with what you see in APSIS One under Audience > Subscriptions.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/folders/topic/sections/com.apsis1.sections.user-created.default-qfbh7w8775/folders \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "discriminator": "com.apsis1.folders.topic.root-nlrl3fhezd",
- "subfolders": [
- {
- "discriminator": "com.apsis1.folders.topic.promotions-pg5fiix3up",
- "name": "Promotions"
}, - {
- "discriminator": "usercreated.targets.springsales-h2d383dnt8",
- "name": "Spring sales"
}
]
}Create a new profile
Unique identifiers
Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace.
Create a new profile
This feature creates a new profile in your account. This profile is identified by the keyspace_discriminator and profile_key you provide in the request. In the section designated by section_discriminator, the value is set for the attribute mapped to the keyspace. This value is the same as the profile key.
This feature allows creating profiles in custom keyspaces (unique identifiers).
The keyspace and section must exist prior to calling this endpoint.
As an example, let's say you want to create a profile in the Email keyspace and the context of your Europe section. Your call would look like this:
POST /audience/keyspaces/com.apsis1.keyspaces.email/sections/usercreated.sections.europe-r6tz73a27t/profiles
{
"profile_key": "com.apsis1.keyspaces.email"
}
Profiles and attributes
Profiles are created on account level whereas attributes and tags are defined on sections. They are then set on profiles on section level as well.
Even though default attributes like First Name or Email have the same names across sections, setting their value on a profile in one section will not affect their values in other sections. Custom attributes and tags created in one section can only set on profiles on that section level.
Mapped attribute values
Each keyspace in the account has a mapped attribute in all sections. For example, the email keyspace, com.apsis1.keyspaces.email, has the Email attribute, com.apsis1.attributes.email, mapped to it in each section.
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
| profile_key required | string Uniquely identifies a profile through a specified keyspace |
Responses
Request samples
- Payload
- Curl
{- "profile_key": "c9251fad-5661-4200-a054-8033963f4c53"
}Response samples
- 201
- 400
- 403
- 404
- 410
- default
{- "keyspace_discriminator": "string",
- "profile_key": "string"
}Lock a profile
Profile will be locked and its data permanently deleted. Profile lock is permanent and irreversible.
APSIS One will generate an encrypted, anonymous ID for the profile and block any future attempts of adding a profile matching this ID. It is not possible to import or create a locked profile nor for them to opt-in again. This applies to all keyspaces.
Unless strictly necessary, abstain from locking Profiles.
Locking Profiles cannot be undone and will prevent individuals from opting in into your communications in the future with the same email address or mobile number.
It is recommended to remove profiles using DELETE /audience/keyspaces/{keyspace_discriminator}/profiles/{profile_key} endpoint instead.
Read more about locking profiles in this Help Center article.
Profiles are on account level
Profiles are created on account level and NOT on section level. Using this endpoint locks the entire profile account-wide, not just its part that belongs to a specific section.
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
Responses
Request samples
- Curl
curl --request PUT \ --url https://api.apsis.one/audience/keyspaces/com.apsis1.keyspaces.email/profiles/john.doe@example.com/locks \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 400
- 403
- 404
- default
{- "status": 400,
- "title": "Bad Request"
}Switch profile unique identifier
Unique identifiers
Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace.
Switch profile unique identifier
This feature removes one of the current profile keys from an existing profile and replaces it with another, new profile key within a different keyspace.
If you only need to change a profile key value within the same keyspace, Set attributes on a profile (version 2) feature is recommended over this one.
How it works
The request path parameters, keyspace, profile key and section, are used to locate the profile that will be changed.
Once the profile is located, the request body specifies two unique identifiers:
from- This unique identifier will be removed from the profile, unless a mapped attribute value exists in another section on that profile (more on that below). This profile key must exist on the profile located via the request path parameters. The unique identifier used to locate the profile can also be targeted with thefromrequest body property.to- This new unique identifier will be created on the profile. Such profile key must not yet exist on the selected profile or any other profile in the account. Also any existing mapped attribute value must correspond to the new profile key value.
After calling this endpoint you are able to locate the profile using the new unique identifier.
Unique identifier removal warning
In most scenarios, this feature removes the the profile key specified in the from request body property from the profile. You will no longer be able to locate the profile using that profile key.
Mapped attribute values
Each keyspace in the account has a mapped attribute in all sections. For example, the email keyspace, com.apsis1.keyspaces.email, has the Email attribute, com.apsis1.attributes.email, mapped to it in each section.
Let's say you're switching to a unique identifier in com.apsis1.keyspaces.email keyspace. This works only if you provide a profile_key value that is the same as the email attribute value for the selected profile.
Now, imagine you're switching from a unique identifier in com.apsis1.keyspaces.crm-id keyspace in the context of a specific section. On top of that, in another section that same profile has a value set on an attribute that is mapped to com.apsis1.keyspaces.crm-id keyspace, the CRM-ID attribute. If that's the case, the original, from profile key is not removed from the profile. The new, to profile key is still created.
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
required | object (UniqueIdentifier) Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace. |
required | object (UniqueIdentifier) Unique identifier is used to locate the profile and consists of a keyspace discriminator and a profile key within that keyspace. Any given profile can have multiple unique identifiers (profile keys) however each of them must belong to a different keyspace. |
Responses
Request samples
- Payload
- Curl
{- "from": {
- "keyspace_discriminator": "com.apsis1.keyspaces.mobile",
- "profile_key": "4812926715"
}, - "to": {
- "keyspace_discriminator": "com.apsis1.keyspaces.crm-id",
- "profile_key": "c9251fad-5661-4200-a054-8033963f4c53"
}
}Response samples
- 400
- 403
- 404
- 409
- 410
- default
{- "status": 400,
- "title": "Bad Request"
}Delete a profile
Profile will be permanently deleted along with its consents and events. This operation is permanent and irreversible.
Read more about deleting profiles in this Help Center article.
Profiles are on account level
Profiles are created on account level and NOT on section level. Using this endpoint deletes the entire profile account-wide, not just its part that belongs to a specific section.
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
Responses
Request samples
- Curl
curl --request DELETE \ --url https://api.apsis.one/audience/keyspaces/com.apsis1.keyspaces.email/profiles/john.doe@example.com \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 400
- 403
- 404
- default
{- "status": 400,
- "title": "Bad Request"
}Merge two profiles
Merges two profiles designated in the body using keyspace discriminator and profile key. As a result of the merge, both profile keys in both keyspaces will point to the same physical profile. Merging profiles using profile keys from different keyspaces is supported. Merge is both associative and commutative so you can do (A+B)+C if you need to merge more than two profiles.
If any of the merged profiles does not exist then it is created along the way. Also, if one of the merged profiles is locked then the other profile will be locked as well if the merge succeeds.
The use of Export Keyspace (com.apsis1.keyspaces.export) for both profiles yields the best results.
Caution! This API does not verify the physical owners of the profiles to be merged. The caller is obliged to make sure both profiles belong to the same physical individual prior to merging them with this endpoint.
Error scenarios
The following error scenarios are specific to this feature:
400 Bad RequestExactly two profiles were not provided in the request body or
profile_keyis not valid404 Not FoundOne of the specified keyspaces or profiles were not found
409 ConflictAttempt to merge two profiles where any of Email, Mobile and/or CRM ID attributes have conflicting values. Update the conflicting attribute value(s) on one of the profiles and retry the merge.
One of the profiles has reached its merge limit of 500 merges per profile
Read more about profile merge in this Help Center article
Authorizations:
Request Body schema: application/jsonrequired
required | Array of objects (ProfileToMerge) = 2 items |
Responses
Request samples
- Payload
- Curl
{- "profiles": [
- {
- "keyspace_discriminator": "com.apsis1.keyspaces.email",
- "profile_key": "john.doe@example.com"
}, - {
- "keyspace_discriminator": "com.apsis1.keyspaces.mobile",
- "profile_key": "46287917256"
}
]
}Response samples
- 400
- 403
- 404
- 409
- default
{- "status": 400,
- "title": "Bad Request"
}Unmerge a profile
Unmerge a profile
Unmerge a single profile designated by the keyspace discriminator and the profile key provided in the request from a group of two or more merged profiles
For example let's assume there are merged profiles A+B+C with keyspaces email + mobile + CRM (respectively). When we request to unmerge profile B via mobile keyspace then profile B is unmerged from A+B+C giving a standalone profile B and merged profile A+C. Data from profile B which was part of A+B+C before the unmerge call remains under A+C profile after profile B has been unmerged.
A previously unmerged profile can be merged back to the same or a new group.
If a profile is stand-alone then a request to unmerge it does not result in an error.
Error scenarios
The following error scenarios are specific to this feature:
400 Bad RequestAn attempt was made to unmerge a canonical profile
404 Not FoundThe specified keyspace or profile was not found
410 GoneThe profile that is requested to be unmerged is locked
Read more about profile merge in this Help Center article
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
Responses
Request samples
- Curl
curl --request DELETE \ --url https://api.apsis.one/audience/profiles/merges/keyspaces/com.apsis1.keyspaces.email/profiles/john.doe@example.com \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 400
- 403
- 404
- 410
- default
{- "status": 400,
- "title": "Bad Request"
}Evaluate a profile
Evaluates a single profile against a given list of segments and returns matches, i.e. a list of segments to which this profile belongs
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
Request Body schema: application/jsonrequired
required | Array of objects non-empty |
| time_zone required | string In segment definition, dates are stored without time zones. Time zone is used to resolve the dates when evaluating a segment, i.e. calculating the profiles to be included in a specific segment. |
Responses
Request samples
- Payload
- Curl
{- "segments": [
- {
- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1"
}, - {
- "discriminator": "com.apsis1.segments.ggs2rfd-Segment2",
- "version_id": "1234"
}
], - "time_zone": "Europe/Stockholm"
}Response samples
- 200
- 400
- 403
- 410
- default
{- "matches": {
- "segments": {
- "com.apsis1.segments.asdfsf2312rfd-Segment1": true,
- "com.apsis1.segments.ggs2rfd-Segment2|1234": false
}
}
}Get segment trend
Get the number of profiles matching the provided provided segment over time. This lets you build a trend graph similar to the one seen in Audience - Segments in APSIS One.
For each sampling point provided in the request, the count of known and unknown profiles is returned.
Sampling points should be provided as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| segment_discriminator required | string Example: usercreated.segments.europe-d8jye63u2y Segment discriminator |
Request Body schema: application/jsonrequired
| sampling_points required | Array of strings <date-time> (DateTime) [ 1 .. 25 ] items [ items <date-time > ] List of instants for which the counts of profiles matching the segment should be returned |
| timezone required | string In segment definition, dates are stored without time zones. Time zone is used to resolve the dates when evaluating a segment, i.e. calculating the profiles to be included in a specific segment. |
Responses
Request samples
- Payload
- Curl
{- "sampling_points": [
- "2021-08-25T12:00:00.000Z",
- "2021-08-26T12:00:00.000Z",
- "2021-08-27T12:00:00.000Z"
], - "timezone": "Europe/Stockholm"
}Response samples
- 200
- 400
- 413
- 429
- default
{- "matching_profile_count": {
- "2021-08-25T12:00:00.000Z": {
- "known": 0,
- "unknown": 0
}, - "2021-08-26T12:00:00.000Z": {
- "known": 352,
- "unknown": 21
}, - "2021-08-27T12:00:00.000Z": {
- "known": 451,
- "unknown": 52
}
}
}Create a consent (version 2)
About consent
If a profile wants to receive communication regarding a specific topic over a specific channel (email or SMS), they must first give consent. The consent information is saved in APSIS One on a profile level along with the topic and the channel the consent is given for.
The following consent types are supported by APSIS One:
opt-in- profile permits communicationopt-out- profile forbids any communicationpending-opt-in- communication permission waits for the profile to confirm it (not supported by APSIS One API yet)confirmed-opt-in- profile permits communication which they also confirmed (not supported by APSIS One API yet)
Confirming the consent, also known as double opt-in, is usually done via a link in an email that is sent to the profile.
Create a consent
Create a profile consent of a specific type regarding a given topic over a selected channel. Provide a reason for consent. Optionally, specify the source of consent which we'll default to One API if not provided.
Profile is identified by keyspace discriminator and profile key. Topic is identified by section discriminator and topic discriminator.
HTTP response status codes specific to this endpoint:
201 Created- a consent to the requested topic did not previously exist on the requested profile and was now created204 No Content- an existing consent to the requested topic was updated409 Conflict- transition from the existing to a desired consent type is not supported (mostly happens when you attempt to update consent type to the same value that is already set on a profile)
More information
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
| topic_discriminator required | string |
| channel_discriminator required | string |
| type required | string Enum: "opt-in" "opt-out" "pending-opt-in" "confirmed-opt-in" Consent type |
| reason required | string [ 3 .. 256 ] characters Reason for giving the consent |
| source | string [ 3 .. 256 ] characters Source of the consent information. Defaults to |
Responses
Request samples
- Payload
- Curl
{- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "channel_discriminator": "com.apsis1.channels.email",
- "type": "opt-in",
- "reason": "Subscribed via summer sale form",
- "source": "Summer sale subscription form"
}Response samples
- 400
- 403
- 404
- 409
- 410
- default
{- "status": 400,
- "title": "Bad Request"
}Get consents (version 2)
About consent
If a profile wants to receive communication regarding a specific topic over a specific channel (email or SMS), they must first give consent. The consent information is saved in APSIS One on a profile level along with the topic and the channel the consent is given for.
The following consent types are supported by APSIS One:
opt-in- profile permits communicationopt-out- profile forbids any communicationpending-opt-in- communication permission waits for the profile to confirm it (not supported by APSIS One API yet)confirmed-opt-in- profile permits communication which they also confirmed (not supported by APSIS One API yet)
Confirming the consent, also known as double opt-in, is usually done via a link in an email that is sent to the profile.
Get consents
Get all or selected types of consents for different topics over various channels currently existing for a specific profile.
Profile is identified by keyspace discriminator and profile key. Topic is identified by section discriminator and topic discriminator.
Suppression
🚧 In development
This feature is currently in development and it's not meant to be used yet
Suppression is the APSIS One feature that allows users to block any communication to a specific address. It takes priority over any profile consents. Useful when one of your customers calls you and requests to halt all communication.
As a result, for a profile to receive any marketing communication from the APSIS One platform, two conditions must be met:
- an opt-in or confirmed opt-in consent for a specific topic over a specific channel must exist on the profile
- the address must not be suppressed
Note that consent is given on the profile level whereas suppression works on the address level.
This APSIS One API endpoint provides information about the existing suppression, if any. Existing suppression for the address that is used as profile_key is always returned. If you need to check if any suppression exists for another address, use suppression_channel_discriminator and suppression_address query string parameters.
In the example response, despite being subscribed to a topic over two channels, the profile will only receive email communication since the address on the SMS channel is suppressed.
More information
Authorizations:
path Parameters
| keyspace_discriminator required | string Example: com.apsis1.keyspaces.email Uniquely identifies a keyspace |
| profile_key required | string Example: john.doe@example.com Uniquely identifies a specific profile in a given keyspace. Profile keys for Email and Mobile keyspaces are normalized and validated as described in Data Tuning in APSIS One API. |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| consent_types | Array of strings Items Enum: "opt-in" "opt-out" "pending-opt-in" "confirmed-opt-in" If provided in the request, this comma separated list of consent types will filter the consents in the response.
For example: |
| suppression_channel_discriminator | string Example: suppression_channel_discriminator=com.apsis1.channels.sms Allows checking if any suppression exists for a specific address. Used together with |
| suppression_address | string Example: suppression_address=41726480987 Allows checking if any suppression exists for a specific address. Used together with |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/v2/audience/keyspaces/com.apsis1.keyspaces.email/profiles/john.doe@example.com/sections/com.apsis1.sections.user-created.default-qfbh7w8775/consents?consent_types=SOME_ARRAY_VALUE&suppression_channel_discriminator=com.apsis1.channels.sms&suppression_address=41726480987' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 400
- 404
- default
{- "items": [
- {
- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "channel_discriminator": "com.apsis1.channels.email",
- "type": "opt-in",
- "reason": "Subscribed via summer sale form",
- "source": "Summer sale subscription form",
- "modified_at": "2017-07-21T17:32:28.761Z"
}, - {
- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "channel_discriminator": "com.apsis1.channels.sms",
- "type": "opt-in",
- "reason": "Subscribed via summer sale form",
- "source": "Summer sale subscription form",
- "modified_at": "2017-07-21T17:32:28.761Z"
}
], - "suppression": [
- {
- "channel_discriminator": "com.apsis1.channels.sms",
- "address": "41726480987",
- "reason": "Customer complain"
}
]
}Request profile import Deprecated
Request a profile import into APSIS One.
Import is an asynchronous operation. Once it's been requested you'll receive a response that contains the file upload URL with embedded credentials and the expiration details.
Upload your import file using that URL. APSIS One API profile import supports CSV files (content type text/csv).
In its requests and responses, APSIS One API supports date and time formatted as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant.
Import files support more date formats as described in this Help Center article. However these dates will be converted to a format corresponding to the type of the attribute the import file column is mapped to. Read more about attribute types in this Help Center article.
Once you've uploaded the file you can check the status using the corresponding GET /audience/sections/{section_discriminator}/imports/{import_id} endpoint.
The manage_subscriptions flag must be true on the keyspace used or HTTP 403 Forbidden response status code is returned.
All the attributes and tags you are trying to set during the import need to be allowed to WRITE through the selected keyspace. If any of them is not, HTTP 403 Forbidden response status code is returned.
Limits
The maximum import file size is 50 MB. Split your import into multiple files and import requests to mitigate this.
Pending import count limit. If reached, HTTP 429 Too Many Requests is returned.
The import file considerations are the same when importing via APSIS One as when importing via this API. They've been described in this Knowledge Base article.
Understanding import failures
For every import, we're generating a report that contains statistics and detailed information about the import errors. See this Knowledge Base article.
Deprecated
Use version 2 instead.
Historically, this endpoint supports creating profile keys in multiple keyspace with one request by adding more than one object inside the keyspace_mappings request body parameter. We're moving away from this behavior in profile imports. When channel-specific topics are enabled on your account, this endpoint no longer supports creating multiple profile keys anymore. A request with multiple keyspace_mappings is rejected with the HTTP 400 Bad Request response status code. In rare cases when multiple profile keys are required, request multiple imports for your profiles.
Inside consent_mappings, for channel-specific topics the channel_discriminator parameter must correspond to the topic_discriminator parameter
Version 2 of the Profile Import feature does not use address_field_selector. Consents are created using the addresses mapped to the Email or Mobile attributes, depending on the consent channel.
More information
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
required | Array of objects [ 1 .. 10 ] items |
object | |
Array of objects <= 5 items | |
Array of objects <= 100 items | |
required | Array of objects [ 1 .. 100 ] items |
Responses
Request samples
- Payload
- Curl
{- "keyspace_mappings": [
- {
- "keyspace_discriminator": "com.apsis1.keyspaces.email",
- "field_selector": "email-address",
- "merge_profiles": false
}
], - "options": {
- "update_existing_profiles": true,
- "clear_existing_attributes": true
}, - "consent_mappings": [
- {
- "address_field_selector": "email-address",
- "consents": [
- {
- "resubscribe_if_opted_out": false,
- "field_selector": "mens-clothing-shoes",
- "channel_discriminator": "com.apsis1.channels.email",
- "consent_list_discriminator": "usercreated.targets.fashion-ufk6unuwec",
- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "type": "opt-in"
}
]
}
], - "tag_mappings": [
- {
- "tag_discriminator": "usercreated.attributes.vip-npqjeo3mbb"
}
], - "attribute_mappings": [
- {
- "field_selector": "address",
- "attribute_version_id": "1234"
}
]
}Response samples
- 201
- 400
- 403
- 404
- 429
- default
{- "import_id": "234345345-c862-4a48-45455-7da1ac0e31ew",
- "file_upload_body": {
- "key": "string",
- "success_action_status": "string",
- "policy": "string",
- "content-type": "string",
- "x-amz-meta-id": "string",
- "x-amz-algorithm": "string",
- "x-amz-credential": "string",
- "x-amz-date": "string",
- "x-amz-signature": "string"
}, - "file_upload_url_expires_at": "string"
}Request profile import (version 2)
Request a profile import into APSIS One.
Import is an asynchronous operation. Once it's been requested you'll receive a response that contains the file upload URL with embedded credentials and the expiration details.
Upload your import file using that URL. APSIS One API profile import supports CSV files (content type text/csv).
In its requests and responses, APSIS One API supports date and time formatted as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant.
Import files support more date formats as described in this Help Center article. However these dates will be converted to a format corresponding to the type of the attribute the import file column is mapped to. Read more about attribute types in this Help Center article.
Once you've uploaded the file you can check the status using the corresponding GET /audience/sections/{section_discriminator}/imports/{import_id} endpoint.
The manage_subscriptions flag must be true on the keyspace used or HTTP 403 Forbidden response status code is returned.
All the attributes and tags you are trying to set during the import need to be allowed to WRITE through the selected keyspace. If any of them is not, HTTP 403 Forbidden response status code is returned.
Limits
The maximum import file size is 50 MB. Split your import into multiple files and import requests to mitigate this.
Pending import count limit. If reached, HTTP 429 Too Many Requests is returned.
The import file considerations are the same when importing via APSIS One as when importing via this API. They've been described in this Knowledge Base article.
Understanding import failures
For every import, we're generating a report that contains statistics and detailed information about the import errors. See this Knowledge Base article.
Version 2
Keyspaces and consents are now independent. You are able to create profiles (and profile keys) in a keyspace of your choice (e.g. CRM) and at the same time create consents for these profiles to the topics that are specific to channels not related to that keyspace (e.g. email or SMS).
Profiles (and profile keys) are created in a single keyspace. Profile merge is not supported.
This version of the Profile Import feature supports two kinds of topics, channel-specific and not, in the following manner:
- If you're creating a consent for a channel-specific topic then you can omit the
channel_discriminatorproperty in the request body. If you provide it then it must match the channel configured for the topic. - To create a consent for a topic that is not channel-specific you need to provide the
channel_discriminatorrequest body property as we need to know over which channel the consent should be created
Inside consent_mappings, the channel is inferred from the topic provided in the topic_discriminator parameter.
More information
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Request Body schema: application/jsonrequired
required | object |
object | |
Array of objects <= 5 items | |
Array of objects <= 100 items | |
required | Array of objects [ 1 .. 100 ] items |
Responses
Request samples
- Payload
- Curl
{- "keyspace_mapping": {
- "keyspace_discriminator": "com.apsis1.keyspaces.email",
- "field_selector": "email-address"
}, - "options": {
- "update_existing_profiles": true,
- "clear_existing_attributes": true
}, - "consent_mappings": [
- {
- "consents": [
- {
- "resubscribe_if_opted_out": false,
- "field_selector": "mens-clothing-shoes",
- "channel_discriminator": "com.apsis1.channels.email",
- "consent_list_discriminator": "usercreated.targets.fashion-ufk6unuwec",
- "topic_discriminator": "usercreated.topics.shoes-bcjvwfknxd",
- "type": "opt-in"
}
]
}
], - "tag_mappings": [
- {
- "tag_discriminator": "usercreated.attributes.vip-npqjeo3mbb"
}
], - "attribute_mappings": [
- {
- "field_selector": "address",
- "attribute_version_id": "1234"
}
]
}Response samples
- 201
- 400
- 403
- 404
- 429
- default
{- "import_id": "234345345-c862-4a48-45455-7da1ac0e31ew",
- "file_upload_body": {
- "key": "string",
- "success_action_status": "string",
- "policy": "string",
- "content-type": "string",
- "x-amz-meta-id": "string",
- "x-amz-algorithm": "string",
- "x-amz-credential": "string",
- "x-amz-date": "string",
- "x-amz-signature": "string"
}, - "file_upload_url_expires_at": "string"
}Get profile import status
Get the status of a profile import requested by POST /audience/sections/{section_discriminator}/imports based on import_id
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| import_id required | string |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/audience/sections/com.apsis1.sections.user-created.default-qfbh7w8775/imports/%7Bimport_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "import_id": "dsfd45e3-435345-4a48-45455-3435fghfg",
- "result": {
- "status": "completed",
- "profiles_found": 99,
- "profiles_processed": 99,
- "profiles_failed": 0
}
}Request profile in segment by consent export
Profile in segment by consent export
Request an export with profiles that fall into the specified segments and have consented to the particular topics via the specific channels.
Options for consent filtering
This feature supports two methods of specifying channels.
Provide single channel
This option is more automated and recommended when you're interested in consent through a single channel, either email or SMS, for all topics you've provided in the request.
Provide your desired channel in the channel_discriminator request body property.
In terms of columns, the export file contains the attribute corresponding to the channel specified in the request: Email attribute for email channel and Mobile attribute for SMS channel.
As for rows, the export file contains the consented profiles. It also contains profiles that have either not consented to receive or unsubscribed from receiving the communication via that channel (email or SMS) and the topics selected via the request parameters. These records contain blank values in Email or Mobile columns.
Provide multiple channels
This recommended option lets you export consent for multiple channels, email and SMS, in one request. It also gives you more flexibility with the export file contents.
Use the channels request body property to provide a mapping from your desired channels to the export file fields.
In the example below I'm interested in email and SMS consents to any of my topics but I also want to export the email and mobile attribute values:
{
"section_discriminator": "usercreated.sections.europe-r6tz73a27t",
"consent_list_discriminator": "usercreated.targets.jeans-3ayb7167e4",
"topic_discriminators": [ "usercreated.topics.bluejeans-cbyntm8qnw", "usercreated.topics.greenjeans-cbyntm8qnw" ],
"channels": [
{ "field_name": "EmailConsent", "channel_discriminator": "com.apsis1.channels.email" },
{ "field_name": "MobileConsent", "channel_discriminator": "com.apsis1.channels.sms" }
],
"attributes": [
{ "field_name": "Email", "attribute_version_id": "1852749" },
{ "field_name": "Mobile", "attribute_version_id": "1852750" }
]
}
The export file for the above request contains email address in the EmailConsent column only for profiles that consented to any of the specified topics via the email channel. Same for MobileConsent and SMS channel.
The other columns, Email and Mobile, are not related to consent. They contain the email and mobile attribute values as requested via the attributes parameter.
| exportKey | EmailConsent | MobileConsent | Mobile | |
|---|---|---|---|---|
| e1ea6ded-61e7-494f-8221-2eb5cf3b2b4d | john@example.com | 41726480987 | john@example.com | 41726480987 |
| d7cdbdf2-b899-4abd-829d-080b93bbc7b7 | karen@example.com | karen@example.com | 48765320019 | |
| 3ff64da9-c436-49df-872d-f40e4a4dee70 | 46895123092 | anna@example.com | 46895123092 | |
| 31e80abd-b890-461f-9e30-e41c87f4d2ff | patrick@example.com | 48700000013 |
In our example John consented to any of the topics via both, email and SMS, and Anna only via SMS.
Excluding unsubscribed profiles
You can use the exclude_unsubscribed_profiles request body parameter to skip the unsubscribed profiles from the export file. If you set it to true, then the profiles that do not currently have an opt-in or confirmed-opt-in consent to any topic from the request via any channel from the request will not be present in the export file.
More on consent types here.
Remaining export file contents
The export file always contains the export key. You can select attributes and tags to include their value as columns in the export file.
For each segments provided in the request body the export file contains a column. These columns are named after the segment names from the request body. A row contains 1 when a corresponding profile matched the segment in question. Otherwise that row says 0.
When exclude_unsubscribed_profiles is true then a subscribed column also appears in the export file. This is for internal use and should not be relied upon by your integration.
How to use
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day.
Call this URL repeatedly with exponential back-off using the same authentication token as for the other APSIS One API calls. Until the result is ready, you will keep getting HTTP 404 Not Found response status code.
As soon as the export file is ready, the poll URL returns HTTP 200 OK and starts streaming a export file as a response.
The HTTP 410 Gone means that the file is no longer available or the ID used is invalid.
Compression
By default the export file is an uncompressed CSV so your code should treat it as .csv. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as .csv.gz.
You can download the same export multiple times using the same poll URL with or without compression.
Additional file format support
By default the export file is a CSV and the Content-Type response header when calling the poll URL is similar to text/csv;charset=UTF-8;header=present. We also support Excel (XLSX) file format. To receive it, provide the Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet request header when calling the poll URL. The response will then contain Content-Type header with the same value.
You can download the same export multiple times using the same poll URL in different file formats.
Limits
Receiving HTTP 413 Payload Too Large from this POST request usually means that the request body contains a number of topics, attributes and/or tags that is currently not supported.
More information
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
| consent_list_discriminator | string Deprecated Consent list that contains the topics to which the profiles consented
|
| topic_discriminators required | Array of strings [ 1 .. 100 ] items Topics to which the profiles consented. They must belong to the consent list provided in this request body. |
| channel_discriminator | string Channel over which the profiles consented. Supported values: |
Array of objects [ 1 .. 2 ] items Channel(s) over which the profiles consented mapped to the export file fields. Cannot be used at the same time as | |
object Allows for including or excluding profiles from the result based on segments. First, provide one or more segments using | |
| duplicate_address_filter | string Exclude duplicate attribute values from the result. Supported
Empty attribute values are not considered duplicate. The time when an attribute value was last updated is considered when comparing via |
Array of objects <= 75 items Attributes to include in the export file | |
Array of objects <= 25 items Tags to include in the export file | |
| limit | integer Limit the export file to a selected number of random profiles |
| exclude_unsubscribed_profiles | boolean You can use the More on consent types here |
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "consent_list_discriminator": "usercreated.targets.fashion-ufk6unuwec",
- "topic_discriminators": [
- "usercreated.topics.shoes-8u78kijgzn",
- "usercreated.topics.hats-udj7e6ywh3"
], - "channel_discriminator": "com.apsis1.channels.email",
- "channels": [
- {
- "field_name": "EmailConsent",
- "channel_discriminator": "com.apsis1.channels.email"
}
], - "segments": {
- "timezone": "Europe/Stockholm",
- "segment_discriminators": {
- "excludeSentInLast": "usercreated.segments.exclude-send-in-last-rjz6b8td2n",
- "europe": "usercreated.segments.europe-d8jye63u2y",
- "testProfile": "usercreated.segments.test-profile-h27w6td542"
}, - "filter": "(!excludeSentInLast & !exampleDomain) | testProfile"
}, - "duplicate_address_filter": "latest",
- "attributes": [
- {
- "field_name": "First Name",
- "attribute_version_id": "67281"
}
], - "tags": [
- {
- "field_name": "VIP Customer",
- "tag_discriminator": "usercreated.attributes.vip-customer-npqjeo3mbb"
}
], - "limit": 25,
- "exclude_unsubscribed_profiles": false
}Response samples
- 201
- 400
- 413
- 429
- default
Count profiles in segment by consent
Count profiles in segment by consent
Request a count of profiles that fall into the specified segments and have consented to the particular topics via the specific channels.
Options for consent filtering
This feature supports two methods of specifying channels. They're described in detail in the accompanying profile in segment by consent export endpoint description.
How to use
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day.
Call this URL repeatedly with exponential back-off using the same authentication token as for the other APSIS One API calls. Until the result is ready, you will keep getting HTTP 404 Not Found response status code.
As soon as the results are in, HTTP 200 OK will pop up along with the results in the response body. Depending on the data volume on the account, the final call to the poll URL can also take longer.
The HTTP 410 Gone means that the file is no longer available or the ID used is invalid.
The response body of a poll URL call that returns HTTP 200 OK is as follows:
{
"profile_count": 7,
"total_profile_count": 7,
"EmailConsent": 11,
"MobileConsent": 10
}
Note that profile_count is deprecated and replaced by total_profile_count.
Note the two additional properties, EmailConsent and MobileConsent. They are optional and their names come from the original POST request body provided by the user as the values of the field_name property inside the channels array.
Limits
Receiving HTTP 413 Payload Too Large from this POST request usually means that the request body contains a number of topics, attributes and/or tags that is currently not supported.
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
| consent_list_discriminator | string Deprecated Consent list that contains the topics to which the profiles consented
|
| topic_discriminators required | Array of strings [ 1 .. 100 ] items Topics to which the profiles consented. They must belong to the consent list provided in this request body. |
| channel_discriminator | string Channel over which the profiles consented. Supported values: |
Array of objects [ 1 .. 2 ] items Channel(s) over which the profiles consented mapped to the export file fields. Cannot be used at the same time as | |
object Allows for including or excluding profiles from the result based on segments. First, provide one or more segments using | |
| duplicate_address_filter | string Exclude duplicate attribute values from the result. Supported
Empty attribute values are not considered duplicate. The time when an attribute value was last updated is considered when comparing via |
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "consent_list_discriminator": "usercreated.targets.fashion-ufk6unuwec",
- "topic_discriminators": [
- "usercreated.topics.shoes-8u78kijgzn",
- "usercreated.topics.hats-udj7e6ywh3"
], - "channel_discriminator": "com.apsis1.channels.email",
- "channels": [
- {
- "field_name": "EmailConsent",
- "channel_discriminator": "com.apsis1.channels.email"
}
], - "segments": {
- "timezone": "Europe/Stockholm",
- "segment_discriminators": {
- "excludeSentInLast": "usercreated.segments.exclude-send-in-last-rjz6b8td2n",
- "europe": "usercreated.segments.europe-d8jye63u2y",
- "testProfile": "usercreated.segments.test-profile-h27w6td542"
}, - "filter": "(!excludeSentInLast & !exampleDomain) | testProfile"
}, - "duplicate_address_filter": "latest"
}Response samples
- 201
- 400
- 413
- 429
- default
Request profile in segment event export
Profile in segment event export
Request profile in segment event export. The export can be requested for specific segment or based on event dates and the data can include attributes, tags, events and topic state.
When segment_filter request parameter is provided, only the profiles from the selected segment are exported, otherwise the export file contains all profiles on the account.
Only the attributes, tags and events explicitly declared in the corresponding request parameters are exported. Even though you're only interested in events, you still need to request at least one attribute or tag for the profiles to even show up in the export file.
Time window for events
For events use start_at (mandatory) and end_at parameters to specify the time period for the exported events. When end_at is not provided in a request, it is defaulted to one week after start_at.
Restrain the event time window as much as you can for your use case. Shorter time windows result in faster export processing and smaller export files that are also quicker to transfer and process. This is especially relevant for larger data sets (high number of very active profiles) and when segment_filter with complex queries is used.
How to use
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day.
Call this URL repeatedly with exponential back-off using the same authentication token as for the other APSIS One API calls. Until the result is ready, you will keep getting HTTP 404 Not Found response status code.
As soon as the export file is ready, the poll URL returns HTTP 200 OK and starts streaming a export file as a response.
The HTTP 410 Gone means that the file is no longer available or the ID used is invalid.
In rare cases when the export processing has failed, calling the poll URL returns HTTP 503 Service Unavailable. If that happens, please request a new export with the POST endpoint.
Compression
By default the export file is an uncompressed JSON so your code should treat it as .json. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as .json.gz.
You can download the same export multiple times using the same poll URL with or without compression.
Export file
The export file is in the JSON format.
On the top level there is a JSON dictionary with profiles. The keys in this dictionary are profile export keys.
For each profile, export file contains sections JSON dictionary. The keys in this dictionary are section IDs. Use "Get sections" endpoint of this API to map these IDs to the specific section definitions.
Each section contains both, attributes and tags, inside the attributes JSON dictionary. The keys in this dictionary are IDs of the attributes and tags. Use "Get attributes" and "Get tags" endpoints of this API to map these IDs to the specific attribute and tag definitions. The objects in this dictionary have the following properties:
valueThe data type of this property depends on the attribute type. For tags the value is always
nulland the sheer fact that the attribute exists in the export file means that the corresponding profile was tagged with this particular tag.
If any event type has been requested for a specified section, the corresponding section object also contains events JSON array. Each object in this array represents a single event and contains the following information:
correlationIdID for the event assigned by the event source (Email Tool). The same
correlationIdvalue may be repeated if the event has been sent multiple times due to a retry logic.sourceEventTimeTime of the event in milliseconds since Unix epoch reported by the event source. This feature was introduced at the beginning of 2020 so events prior to that may have
event_timeequal to0. The value of0is also possible when the event source did not specify the event time.typeIdEvent version ID. Use "Get events" endpoint of the API to map these IDs to the specific event definitions.
createdAtTime of the event in milliseconds since Unix epoch as seen on Audience server when it received the event.
dataData specific to a particular event type as defined by "Get events" endpoint of the API
Limits
The export file can include up to 75 attributes and 25 tags. Validated when requesting an export.
Pending export count limit. If reached, HTTP 429 Too Many Requests is returned.
If you request an export with many attributes or a large time window that results in many events, you may receive a status of error when attempting to request or download an export. You can then retry the export request aiming at a smaller data subset.
Usually the errors in processing are caused by:
- using too complex segments
- providing too many attributes and/or tags
- providing too many event types
More information
Authorizations:
Request Body schema: application/jsonrequired
object Select profiles based on an existing segment. Read more in these Help Center articles. | |
Array of objects <= 75 items Attributes to include in the export file | |
Array of objects <= 25 items Tags to include in the export file | |
object Events to include in the export file |
Responses
Request samples
- Payload
- Curl
{- "segment_filter": {
- "timezone": "Europe/Stockholm",
- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1",
- "version_id": "821271"
}, - "attributes": [
- {
- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "attribute_version_id": "67281"
}
], - "tags": [
- {
- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "tag_discriminator": "usercreated.attributes.last-minute-npqjeo3mbb"
}
], - "events": {
- "start_at": "string",
- "end_at": "string",
- "types": [
- {
- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "event_version_id": "725132"
}
]
}
}Response samples
- 201
- 429
- default
{- "file_download_url": "https://exports.api.apsis.one/audience/profiles/exports/e4994c5b-e8fd-48ab-9b1b-9d5d2e6ac378"
}Request single profile export (beta)
Beta
This is a new feature in APSIS One API and we are still keeping a close look on performance and potential issues. Please report any feedback to customerservice.apsis@efficy.com.
Single profile export
Export a single profile, identified by the export key, together with their attribute values (and optionally the change history of these) and events.
This endpoint is asynchronous via callbacks.
How it works
Call this endpoint providing a callback_url which is a public endpoint that accepts HTTP POST requests. For example:
{
"callback_url": "https://example.com/callbacks/single-profile-export"
}
Provided your call is correct, you should receive an empty HTTP 202 Accepted response and after a while your server under callback_url should receive an HTTP POST call with the body similar to the following:
{
"code": 100,
"message": "Callback verified"
}
When we're ready, we will call the callback_url server again and provide it with the URL to fetch the actual data:
{
"code": 200,
"message": "https://api.apsis.one/audience/profiles/export-single/accounts/test/definitions/01af2d3c-d30d-43ec-8f47-996c881148b4?metadata=true"
}
Finally, call that URL with a GET verb and the auth token usually used for APSIS One API to get your export file.
Export file
An example export file follows this structure:
{
"profiles": {
"<export key>": {
"sections": {
"<section ID>": {
"attributes": { },
"events": [ ]
}
}
}
},
"metadata": {
"sections": {
"<section ID>": {
"events": { },
"attributes": { }
}
}
}
}
The profiles object contains the attribute values and event instances that exist in the profile in any section.
The metadata object contains attribute and event definitions for these sections.
If include_attribute_history is set to true the changes to attribute values are also included. They appear inside the attributes object as history.
If include_type_definitions is set to true the export payload also contains the metadata object with type definitions per section.
If include_merged_profiles is set to true more profile keys may appear in the profiles object depending on whether the originally requested profile has been merged or not.
Authorizations:
path Parameters
| export_key required | string Example: 2a3bc7a3-a75f-463c-871d-42f378c019e9 Uniquely identifies a specific profile on the account. You can obtain it from various exports supported by the APSIS One API and from the browser address bar when viewing a profile. |
Request Body schema: application/jsonrequired
| callback_url required | string <uri> Public endpoint that accepts HTTP |
| include_merged_profiles | boolean Include the data of all merged profiles |
| include_attribute_history | boolean Include the data of attribute value changes |
| include_type_definitions | boolean Include the data of type definition per section |
Responses
Callbacks
Request samples
- Payload
- Curl
{- "include_merged_profiles": false,
- "include_attribute_history": false,
- "include_type_definitions": false
}Response samples
- 400
- 404
- 429
- default
{- "status": 400,
- "title": "Bad Request"
}Callback payload samples
{- "status": 200,
- "message": "Export complete",
}Request duplicate profile in segment by consent export
Duplicate profile in segment by consent export
Request an export with profiles that share a specific attribute value.
You can filter the results further by including only the profiles from existing segments or matching provided AQL queries. Provide the existing segments in segment_discriminators or AQL queries in segment_definitions. You also need to send the filter property with a simple logical expression that references the segment discriminator or definition names. You can use either discriminators or definitions. For example:
"segments": {
"timezone": "Europe/Stockholm",
"segment_discriminators": {
"women": "usercreated.segments.women-rjz6b8td2n",
"europe": "usercreated.segments.europe-d8jye63u2y"
},
"filter": "!(europe) & women"
},
The AQL queries can be obtained by calling APSIS One API endpoints that provide them for specific scenarios. For example, to export all profiles who opened a specific email, use the AQL query returned by Get a specific email activity.
You can also filter the results by including only the profiles who subscribed to specific topics. Provide one or more topic_discriminators and channel_discriminator to achieve this. For example:
"topic_discriminators": [
"usercreated.topics.shoes-8u78kijgzn",
"usercreated.topics.hats-udj7e6ywh3"
],
"channel_discriminator": "com.apsis1.channels.email"
The export file always contains the export key. You can select other attributes and tags to include their value as columns in the export file.
Downloading the requested export file
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day. Call this URL repeatedly with exponential back-off using HTTP GET and the same authentication token as for the other APSIS One API calls. You will be getting one of the following responses:
HTTP 404 Not Found- export in progress, the export file is no longer available or the ID provided is invalidHTTP 200 OK- the export file is ready and is immediately streamed as a responseHTTP 410 Gone- the export file is no longer available or the ID provided is invalid
Export file format
The Content-Type response header received when calling the poll URL specifies the export file format. Provide the Accept request header when calling the poll URL to select a different export file format. Supported values for these headers are:
- CSV:
text/csv;charset=UTF-8;header=present(default) - Excel:
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
You can download the same export multiple times using the same poll URL in different file formats.
Export file compression
By default the export file is not compressed so your code should treat it as, depending on the file format, .csv for example. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as, depending on the file format, .csv.gz.
You can download the same export multiple times using the same poll URL with or without compression.
Limits
Receiving HTTP 413 Payload Too Large from this POST request usually means that the request body contains a number of topics, attributes and/or tags that is currently not supported.
More information
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
| consent_list_discriminator | string Deprecated Consent list that contains the topics to which the profiles consented
|
| topic_discriminators | Array of strings <= 100 items Topics to which the profiles consented |
| channel_discriminator | string Channel over which the profiles consented to the topics from |
object Provide one or more segments using | |
| find_duplicates_by_attribute_version_id required | string The report will contain profiles that share the value for this attribute. |
Array of objects <= 75 items Attributes to include in the export file | |
Array of objects <= 25 items Tags to include in the export file | |
| limit | integer Limit the export file to a selected number of random profiles |
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "consent_list_discriminator": "usercreated.targets.fashion-ufk6unuwec",
- "topic_discriminators": [
- "usercreated.topics.shoes-8u78kijgzn",
- "usercreated.topics.hats-udj7e6ywh3"
], - "channel_discriminator": "com.apsis1.channels.email",
- "segments": {
- "timezone": "Europe/Stockholm",
- "segment_discriminators": {
- "excludeSentInLast": "usercreated.segments.exclude-send-in-last-rjz6b8td2n",
- "europe": "usercreated.segments.europe-d8jye63u2y",
- "testProfile": "usercreated.segments.test-profile-h27w6td542"
}, - "segment_definitions": {
- "excludeSentInLast": "section(14230).event(468206).inLast(\"events.hour\",48)",
- "exampleDomain": "section(14230).attribute(404068).contains(\"@example.com\")",
- "testProfile": "section(14230).attribute(404068).contains(\"test@\")"
}, - "filter": "(!excludeSentInLast & !exampleDomain) | testProfile"
}, - "find_duplicates_by_attribute_version_id": "67281",
- "attributes": [
- {
- "field_name": "First Name",
- "attribute_version_id": "67281"
}
], - "tags": [
- {
- "field_name": "VIP Customer",
- "tag_discriminator": "usercreated.attributes.vip-customer-npqjeo3mbb"
}
], - "limit": 25
}Response samples
- 201
- 400
- 413
- 429
- default
Request profile in segment export (beta)
Beta
This is a new feature in APSIS One API and we are still keeping a close look on performance and potential issues. Please report any feedback to customerservice.apsis@efficy.com.
Profile in segment export
Request an export with profiles from an existing segment (using segment_discriminator) or matching a provided AQL query (using segment_definition).
The AQL queries can be obtained by calling APSIS One API endpoints that provide them for specific scenarios. For example, to export all profiles who opened a specific email, use the AQL query returned by Get a specific email activity.
Optionally specify to include known or unknown profiles only.
The export file always contains the export key. You can select other attributes and tags to include their value as columns in the export file.
Downloading the requested export file
Once executed successfully, this endpoint returns a poll URL that is valid for 1 day. Call this URL repeatedly with exponential back-off using HTTP GET and the same authentication token as for the other APSIS One API calls. You will be getting one of the following responses:
When using the poll URL from file_download_url_v2 (in development):
HTTP 202 Accepted- export in progressHTTP 200 OK- the export file is ready and is immediately streamed as a responseHTTP 410 Gone- the export file is no longer availableHTTP 404 Not Found- the ID provided is invalid
When using the poll URL from file_download_url:
HTTP 404 Not Found- export in progress, the export file is no longer available or the ID provided is invalidHTTP 200 OK- the export file is ready and is immediately streamed as a responseHTTP 410 Gone- the export file is no longer available or the ID provided is invalid
Export file format
The Content-Type response header received when calling the poll URL specifies the export file format. Provide the Accept request header when calling the poll URL to select a different export file format. Supported values for these headers are:
- CSV:
text/csv;charset=UTF-8;header=present(default) - Excel:
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - JSON:
application/json(in development)
You can download the same export multiple times using the same poll URL in different file formats.
Export file compression
By default the export file is not compressed so your code should treat it as, depending on the file format, .csv for example. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as, depending on the file format, .csv.gz.
You can download the same export multiple times using the same poll URL with or without compression.
Limits
Receiving HTTP 413 Payload Too Large from this POST request usually means that the request body contains a number of attributes and/or tags that is currently not supported.
More information
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
required | object Provide a segment using |
| known_profiles | boolean Optional parameter that allows for known and unknown profiles filtering
|
Array of objects <= 75 items Attributes to include in the export file | |
Array of objects <= 25 items Tags to include in the export file | |
| limit | integer Limit the export file to a selected number of random profiles |
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "segment": {
- "timezone": "Europe/Stockholm",
- "segment_discriminator": "usercreated.segments.exclude-send-in-last-rjz6b8td2n"
}, - "known_profiles": null,
- "attributes": [
- {
- "field_name": "First Name",
- "attribute_version_id": "67281"
}
], - "tags": [
- {
- "field_name": "VIP Customer",
- "tag_discriminator": "usercreated.attributes.vip-customer-npqjeo3mbb"
}
], - "limit": 25
}Response samples
- 201
- 400
- 413
- 429
- default
{- "file_download_url_v2": "https://exports.api.apsis.one/audience/profiles/reports/segments/v2/e4994c5b-e8fd-48ab-9b1b-9d5d2e6ac378"
}Count profiles in segment (beta)
Beta
This is a new feature in APSIS One API and we are still keeping a close look on performance and potential issues. Please report any feedback to customerservice.apsis@efficy.com.
Profile in segment count
Request a count of profiles from an existing segment or matching a provided AQL query. Optionally specify to include known or unknown profiles only.
See the corresponding profile in segment export for more information about AQL queries.
More information
Authorizations:
Request Body schema: application/jsonrequired
| section_discriminator required | string Section to which the profiles belong |
required | object Provide a segment using |
| known_profiles | boolean Optional parameter that allows for known and unknown profiles filtering
|
Responses
Request samples
- Payload
- Curl
{- "section_discriminator": "com.apsis1.sections.user-created.default-qfbh7w8775",
- "segment": {
- "timezone": "Europe/Stockholm",
- "segment_discriminator": "usercreated.segments.exclude-send-in-last-rjz6b8td2n"
}, - "known_profiles": null
}Response samples
- 200
- 400
- 413
- 429
- default
{- "profile_count": 7
}Get all recent email activities
Returns all recent email activities. The maximum of 500 recent activities are returned sorted by created_at.
When include_statistics parameter is provided and set to true then activity statistics are also included in the response but only if they have been calculated (e.g. email has been sent).
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_statistics | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/emails/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities?include_statistics=SOME_BOOLEAN_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer campaign sending",
- "status": "sent",
- "created_at": "2017-07-21T17:32:28.761Z",
- "sent_at": "2017-07-21T17:32:28.761Z",
- "email_subject": "Summer sale",
- "statistics": {
- "sent": 6000,
- "delivered": 5900,
- "delivery_rate": 43.3,
- "opens": 4500,
- "unique_opens": 4400,
- "open_rate": 55.2,
- "clicks": 3499,
- "unique_clicks": 3200,
- "click_rate": 44.7,
- "click_to_open_rate": 33.4,
- "bounces": 300,
- "bounce_rate": 20.5,
- "unsubscribes": 100,
- "unsubscribe_rate": 2.3,
- "spam_complaints": 100,
- "spam_complaint_rate": 0.3
}
}
]
}Get a specific email activity
Returns a specific email activity.
Provides AQL queries to build segments that return profiles based on specific criteria. They can be used with profile in segment export.
When include_statistics parameter is provided and set to true then activity statistics are also included in the response but only if they have been calculated (e.g. email has been sent).
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| activity_id required | string Example: 1b59132e-1280-4b33-23ed-293b5f42e3ae The ID of Email, SMS, Website, Marketing Automation, Product Recommendations, Forms or Pages activity |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_statistics | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/emails/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/1b59132e-1280-4b33-23ed-293b5f42e3ae?include_statistics=SOME_BOOLEAN_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer campaign sending",
- "status": "sent",
- "created_at": "2017-07-21T17:32:28.761Z",
- "sent_at": "2017-07-21T17:32:28.761Z",
- "email_subject": "Summer sale",
- "statistics": {
- "sent": 6000,
- "delivered": 5900,
- "delivery_rate": 43.3,
- "opens": 4500,
- "unique_opens": 4400,
- "open_rate": 55.2,
- "clicks": 3499,
- "unique_clicks": 3200,
- "click_rate": 44.7,
- "click_to_open_rate": 33.4,
- "bounces": 300,
- "bounce_rate": 20.5,
- "unsubscribes": 100,
- "unsubscribe_rate": 2.3,
- "spam_complaints": 100,
- "spam_complaint_rate": 0.3
}, - "aql_queries": {
- "sent": "(section(56019).event(1040147).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "delivered": "(section(56019).event(8263452).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "opens": "(section(56019).event(7622133).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "clicks": "(section(56019).event(8273561).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "bounces": "(section(56019).event(3672813).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "spam_complaints": "(section(56019).event(7825113).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "unsubscribes": "(section(56019).event(6712313).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))"
}
}Request email event export
Email event export
Request an export of email events decorated with selected attributes and tags since the specific start_at date, optionally to a specific end_at date.
You can also target a specific segment via the segment_filter property.
Generating an export is an asynchronous operation. Once it's been requested you can check the status and obtain the download link using the corresponding Get email event export status endpoint.
Export file
The following events are included in the export file:
- Sent
- Delivered
- Bounced
- Open
- Clicked
- Unsubscribed
- Reported spam
The export file is a GZIP compressed CSV file containing the following default columns:
activity_idID of the main activity. Activities can have sub-activities in case of split testing.
split_idActivity ID of this event's sub-activity. Same as
activity_idfor non-split sendings and the winning partition in split tests.activity_nameName given to the activity
split_activity_nameName of the split group
senderEmail sender name
subjectEmail subject
addressPrimary email address attribute of the targeted profile (from the same data section as the event)
variationSplit test recipient group. Empty for non-split sendings.
typeEvent type
SENTDELIVEREDOPENEDCLICKEDBOUNCEDUNSUBSCRIBEDABUSE
correlation_idID for the event assigned by the event source (Email Tool). The same
correlation_idvalue may be repeated if the event has been sent multiple times due to a retry logic.event_timeTime of the event in milliseconds since Unix epoch reported by the event source. This feature was introduced at the beginning of 2020 so events prior to that may have
event_timeequal to0. The value of0is also possible when the event source did not specify the event time. The dates in 1970 are possible when the event source specified the event time as0since they're interpreted as Unix epoch.server_timeTime in milliseconds since Unix epoch when the event was received by One
deviceOnly for
CLICKEDandOPENEDevents. Values may be extended with new values and with additional data as suffix.TABLETMOBILEDESKTOPSMART_TVUNKNOWN
locationOnly for
CLICKEDandOPENEDevents. ISO 3166-1 alpha-2. May be extended with new data as suffix.link_idOnly for
CLICKEDevents. ID of the link.link_urlOnly for
CLICKEDevents. URL of the link target.link_titleOnly for
CLICKEDevents. Title given to the link in the email template.bounce_codeOnly for
BOUNCEDevents. Detailed bounce reason.- 1000-1999 Rejected by recipient's server
- 2000-2999 Invalid address (permanent)
- 2001 Email address does not exist
- 2002 Domain of address does not exist
- 2004 Closed email account
- 3000-3999 Address is temporarily unavailable
- 3001 Mailbox is full
- 3002 Recipient server is too busy
- 3003 Email account is inactive
- 4000-4999 Technical delivery problem
- 4003 Network error
- 4007 SPF authentication error
- 4008 DMARC authentication error
- 4009 DKIM authentication error
- 5000-5999 Informational (out of office, auto reply etc.)
- 9999 Unknown failure
unsubscribe_topicOnly for
UNSUBSCRIBEDevents. Discriminator of the unsubscribed topic.abuse_sectionOnly for
ABUSEevents. Discriminator of the abuse.
On top of the default columns the export file contains the fields requested in additional_attribute_mappings property for attributes and additional_tag_mappings property for tags. These have the headers following this pattern: gender (version_id: 491874). When a field is a tag, then the fact of it being set is denoted by the constant TAG in the export file.
In its requests and responses, APSIS One API supports date and time formatted as ISO 8601 referred to as date-time in RFC 3339, section 5.6 in the UTC variant.
Date format in the export files follows the type of the attribute. Read more about attribute types in this Help Center article.
Limits
Maximum export time window for events is three months. Validated when requesting a export.
The export file can contain up to 500 attributes and tags in total. Validated when requesting a export.
Pending export count limit. If reached, HTTP 429 Too Many Requests is returned.
Maximum file size limit. If you request a export with very large data set, i.e. many attributes or large time window that results in many events, you may receive a status of error when calling GET /emails/reports/{report_id}. You can then retry the export request aiming at a smaller data subset.
If there are over 25 sections on the account then HTTP 413 Request Entity Too Large may be returned
About events
Events are created in response to actions performed on activities. A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Email activities can be fetched using the following endpoints:
- recent activities:
GET /emails/sections/{section_discriminator}/activities - specific activity:
GET /emails/section/{section_discriminator}/activities/{activity_id}
More information
Authorizations:
Request Body schema: application/jsonoptional
| start_at required | string <date-time> Date and time formatted as ISO 8601 referred to as |
| end_at | string <date-time> Date and time formatted as ISO 8601 referred to as |
object Select profiles based on an existing segment. Read more in these Help Center articles. | |
Array of objects <= 75 items Include profile attributes in this list to receive them as fields in the export file on top of the default event properties | |
Array of objects <= 25 items Include profile tags in this list to receive them as fields in the export file on top of the default event properties |
Responses
Request samples
- Payload
- Curl
{- "start_at": "string",
- "end_at": "string",
- "segment_filter": {
- "timezone": "Europe/Stockholm",
- "discriminator": "com.apsis1.segments.asdfsf2312rfd-Segment1",
- "version_id": "821271"
}, - "additional_attribute_mappings": [
- {
- "field_name": "CRM-ID",
- "section_discriminator": "com.apsis.sections.user-created",
- "attribute_version_id": "67281"
}
], - "additional_tag_mappings": [
- {
- "field_name": "custom-tag-1",
- "section_discriminator": "com.apsis.sections.user-created",
- "tag_discriminator": "usercreated.attributes.export-tag-1-asd69"
}
]
}Response samples
- 201
- 400
- 404
- 429
- default
{- "report_id": "1b59132e-1280-4b33-a096-293b5f42e3ae"
}Get email event export status
Get the status an email event export previously requested using the Request email event export endpoint based on report_id.
Downloading the export file
When the status response property is completed then the export file is ready for download. In such case the response contains the file_download_url property. Use a GET request along with this URL to download the export file.
The file_download_url_expires_at is also provided and instructs you until when the URL is valid. Should you wish to download the same export file multiple times, you need to call this endpoint again to refresh the URL.
Finally, file_expires_at tells you until when the specific export, identified by the report_id, is guaranteed to be kept available for download.
Authentication via headers
Export file download URL is secure. If you wish to further increase its security, you can opt for transmitting the authentication via headers instead of the query string.
To do this, provide the header_auth request query string parameter as true when calling this endpoint.
If you do that, the file_download_url response property does not contain the data required to authenticate the export file download. Instead, a token is returned inside the x-apsis-auth response header.
When attempting to download the file using the URL generated this way you need to provide this token as a x-apsis-auth request header.
Authorizations:
path Parameters
| report_id required | string Example: 1b59132e-1280-4b33-a096-293b5f42e3ae |
query Parameters
| header_auth | boolean Example: header_auth=true When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/emails/reports/1b59132e-1280-4b33-a096-293b5f42e3ae?header_auth=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "report_id": "1b59132e-1280-4b33-a096-293b5f42e3ae",
- "result": {
- "status": "completed",
- "message": "Report generated successfully and is available for download",
- "file_expires_at": "string",
- "file_download_url_expires_at": "string"
}
}Get all recent SMS activities
Returns all recent SMS activities. The maximum of 500 recent activities are returned sorted by created_at.
When include_statistics parameter is provided and set to true then activity statistics are also included in the response but only if they have been calculated (e.g. SMS has been sent).
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_statistics | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/sms/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities?include_statistics=SOME_BOOLEAN_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer campaign sending",
- "status": "sent",
- "created_at": "2017-07-21T17:32:28.761Z",
- "statistics": {
- "sent": 6000,
- "delivered": 5000,
- "delivery_rate": 40.2,
- "clicks": 3000,
- "click_rate": 23.4,
- "bounces": 100,
- "bounce_rate": 100,
- "unsubscribes": 100,
- "unsubscribe_rate": 3.4
}
}
]
}Get a specific SMS activity
Returns a specific SMS activity.
Provides AQL queries to build segments that return profiles based on specific criteria. They can be used with profile in segment export.
When include_statistics parameter is provided and set to true then activity statistics are also included in the response but only if they have been calculated (e.g. SMS has been sent).
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| activity_id required | string Example: 1b59132e-1280-4b33-23ed-293b5f42e3ae The ID of Email, SMS, Website, Marketing Automation, Product Recommendations, Forms or Pages activity |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| include_statistics | boolean When |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/sms/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/1b59132e-1280-4b33-23ed-293b5f42e3ae?include_statistics=SOME_BOOLEAN_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer campaign sending",
- "status": "sent",
- "created_at": "2017-07-21T17:32:28.761Z",
- "statistics": {
- "sent": 6000,
- "delivered": 5000,
- "delivery_rate": 40.2,
- "clicks": 3000,
- "click_rate": 23.4,
- "bounces": 100,
- "bounce_rate": 100,
- "unsubscribes": 100,
- "unsubscribe_rate": 3.4
}, - "aql_queries": {
- "sent": "(section(56019).event(1040147).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "delivered": "(section(56019).event(8263452).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "clicks": "(section(56019).event(8273561).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "bounces": "(section(56019).event(3672813).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))",
- "unsubscribes": "(section(56019).event(6712313).eventData(\"activityId\").eq(\"6b3d2f34-363f-4ec0-8880-5573364cfdc0\"))"
}
}Get all recent Website activities
Returns all recent Website activities. The maximum of 500 recent activities are returned.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/website/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Cookie banner",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "active"
}
]
}Get a specific Website activity
Returns a specific Website activity.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| activity_id required | string Example: 1b59132e-1280-4b33-23ed-293b5f42e3ae The ID of Email, SMS, Website, Marketing Automation, Product Recommendations, Forms or Pages activity |
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/website/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/1b59132e-1280-4b33-23ed-293b5f42e3ae \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Cookie banner",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "active"
}Get all recent Marketing Automation activities
Returns all recent Marketing Automation activities. The maximum of 500 recent activities are returned.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
query Parameters
| trigger_types | Array of strings (TriggerType) Items Value: "api" If provided in the request, this comma separated list of trigger types will filter the activities in the response. For example By default, activities are not filtered by trigger types. |
Responses
Request samples
- Curl
curl --request GET \ --url 'https://api.apsis.one/marketing-automation/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities?trigger_types=SOME_ARRAY_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 400
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Confirmation sender",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "finished",
- "description": "Sends confirmations to people who subscribed"
}
]
}Get a specific Marketing Automation activity
Returns a specific Marketing Automation activity.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
| activity_id required | string Example: 1b59132e-1280-4b33-23ed-293b5f42e3ae The ID of Email, SMS, Website, Marketing Automation, Product Recommendations, Forms or Pages activity |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/marketing-automation/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities/1b59132e-1280-4b33-23ed-293b5f42e3ae \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
- default
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Confirmation sender",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "finished",
- "description": "Sends confirmations to people who subscribed"
}Get all recent Forms & Pages activities
Returns all recent Forms & Pages activities. The maximum of 500 recent activities are returned.
A relationship between an activity and an event is found through activity ID. Activity is a source of an event.
Authorizations:
path Parameters
| section_discriminator required | string Example: com.apsis1.sections.user-created.default-qfbh7w8775 Section discriminator |
Responses
Request samples
- Curl
curl --request GET \ --url https://api.apsis.one/forms-and-pages/sections/com.apsis1.sections.user-created.default-qfbh7w8775/activities \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Response samples
- 200
- 404
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Summer sale subscription form",
- "created_at": "2017-07-21T17:32:28.761Z",
- "status": "active"
}
]
}