# attentive Documentation > Documentation for attentive Append .md to any documentation page URL to get its markdown version. ## Guides - [Introduction to Attentive APIs](https://docs.attentive.com/docs/introduction.md) - [Partner with Attentive](https://docs.attentive.com/docs/partner-with-attentive.md) - [Authentication](https://docs.attentive.com/docs/authentication.md) - [Create and Manage Custom Apps](https://docs.attentive.com/docs/create-and-manage-custom-apps.md) - [Distribute Your App](https://docs.attentive.com/docs/distribute-your-app.md) - [Publish Your App](https://docs.attentive.com/docs/publish-your-app.md) - [Attentive SSO Setup - SAML](https://docs.attentive.com/docs/attentive-sso-setup-saml.md) - [API Rate Limits](https://docs.attentive.com/docs/api-rate-limits.md) - [API Testing Console](https://docs.attentive.com/docs/api-testing-console.md) - [Webhooks Overview](https://docs.attentive.com/docs/overview.md) - [Webhook Authentication](https://docs.attentive.com/docs/webhook-authentication.md) - [Create and Manage Webhooks](https://docs.attentive.com/docs/create-and-manage-webhooks.md) - [Best Practices](https://docs.attentive.com/docs/best-practices.md) - [Webhook Payloads](https://docs.attentive.com/docs/webhook-payloads.md) - [About the Attentive MCP Server](https://docs.attentive.com/docs/mcp-about.md) - [Access and Permissions](https://docs.attentive.com/docs/mcp-access-and-permissions.md) - [Installation](https://docs.attentive.com/docs/mcp-installation.md) - [Working Across Companies](https://docs.attentive.com/docs/mcp-working-across-companies.md) - [Capabilities and available tools](https://docs.attentive.com/docs/mcp-capabilities.md) - [Example Prompts](https://docs.attentive.com/docs/mcp-example-prompts.md) - [Data, Privacy, and Security](https://docs.attentive.com/docs/mcp-privacy-and-security.md) - [Limitations](https://docs.attentive.com/docs/mcp-limitations.md) - [Troubleshooting](https://docs.attentive.com/docs/mcp-troubleshooting.md) - [Frequently Asked Questions](https://docs.attentive.com/docs/mcp-frequently-asked-questions.md) - [Attentive Tag SDK](https://docs.attentive.com/docs/attentive-tag-sdk.md) - [Google Tag Manager SDK](https://docs.attentive.com/docs/google-tag-manager-sdk.md) - [GTM SDK via Attentive Analytics Template](https://docs.attentive.com/docs/gtm-sdk-via-attentive-analytics-template.md) - [Mobile SDKs](https://docs.attentive.com/docs/mobile-sdks.md) - [Attentive iOS SDK](https://docs.attentive.com/docs/attentive-ios-sdk-guide.md) - [Attentive Android SDK](https://docs.attentive.com/docs/attentive-android-sdk-guide.md) - [Configuring iOS Push Credentials (APNs)](https://docs.attentive.com/docs/configuring-ios-push-credentials-apns.md) - [Configuring Android Push Credentials (FCM)](https://docs.attentive.com/docs/configuring-android-push-credentials-fcm.md) - [Updating Your Mobile SDK Version](https://docs.attentive.com/docs/updating-mobile-sdk-version.md) - [Attentive SFTP Data Feeds](https://docs.attentive.com/docs/attentive-sftp-data-feeds.md) - [Connect to Attentive SFTP](https://docs.attentive.com/docs/connect-to-attentive-sftp.md) - [Daasity SFTP](https://docs.attentive.com/docs/daasity-sftp.md) - [Event Data Field Definitions](https://docs.attentive.com/docs/event-data-field-definitions.md) - [Optimove Segments](https://docs.attentive.com/docs/optimove-segments.md) - [Subscriber Segment Upload](https://docs.attentive.com/docs/subscriber-segment-upload.md) - [Integrations](https://docs.attentive.com/docs/third-party-integrations.md) ## API Reference - [Test Authentication V2](https://docs.attentive.com/reference/test-authentication-v2.md) - [Me](https://docs.attentive.com/reference/getmev2.md): Make a call to this endpoint to test your unique token that you generate in the Attentive product. - [User Attributes](https://docs.attentive.com/reference/user-properties.md) - [Bulk User Attributes](https://docs.attentive.com/reference/postbulkuserattributes.md): This endpoint allows clients to submit multiple user attribute updates in bulk, accepting up to 256 payloads per request. Each request is validated, and a unique batch ID is returned for tracking the status of the batch. Each individual record must not exceed 1 MiB (1,048,576 bytes). Records that exceed this limit are rejected with a `413` in the job results and are not processed. Scopes Required: [attributes:all, subscriptions:all] Default Rate Limit: 100 requests per second - [Create or update a single user with attributes, subscriptions, and identifiers](https://docs.attentive.com/reference/postuserattributes.md): Creates or updates a single user record, including associated attributes, subscriptions, and identifiers. If a user with the provided identifiers already exists, their information will be updated; otherwise, a new user will be created. There is a limit of 100 of custom attributes that can be created. If intending to update an existing attribute, the name of the key must match the name of the existing attribute. If an existing attribute does not exist, a new attribute will be created with the given key as the name. Attributes with enumerated values must have a value that matches an existing enum value; new enum values will not be created. Attempting to pass custom attributes as an array or a map such as `["New York City]` or `{"favorite city": "Boston"}` will result in a 400 error. Default Rate Limit: 150 requests per second - [Segments ( Open Beta )](https://docs.attentive.com/reference/segments.md) - [Create new segment](https://docs.attentive.com/reference/createsegment.md): Creates a new empty segment with the specified name and optional description. Scopes Required: [segments:Write] Default Rate Limit: 100 requests per second - [List segments](https://docs.attentive.com/reference/listsegments.md): Lists segments with optional filtering by name, external ID, or update timestamp. Scopes Required: [segments:Read OR segments:Write] Default Rate Limit: 100 requests per second - [Get segment by external ID](https://docs.attentive.com/reference/getsegmentbyexternalid.md): Retrieves segment details by external ID. Scopes Required: [segments:Read OR segments:Write] Default Rate Limit: 100 requests per second - [Partial update segment by external ID](https://docs.attentive.com/reference/patchsegmentbyexternalid.md): Partially updates an existing segment. Only provided fields will be updated. Scopes Required: [segments:Write] Default Rate Limit: 100 requests per second - [Archive segment by external ID](https://docs.attentive.com/reference/deletesegmentbyexternalid.md): Archives (soft deletes) a segment by external ID. The segment will no longer be visible in list operations but can be restored if needed. Scopes Required: [segments:Write] Default Rate Limit: 100 requests per second - [Bulk Segment Operations ( Open Beta )](https://docs.attentive.com/reference/bulk-segment-operations.md) - [Add Bulk Segment Members](https://docs.attentive.com/reference/postbulksegmentmembers.md): Add members to a segment in bulk. This endpoint accepts 1 to 10,000 members per request. Members are identified by email, phone number, and/or client user ID. The request is validated, queued for asynchronous processing, and a unique batch job ID is returned for tracking the status. **Request Limits:** - Minimum: 1 member per request - Maximum: 10,000 members per request - Each individual record must not exceed 1 MiB (1,048,576 bytes); oversized records are rejected with a `413` in the job results and are not processed - At least one identifier (email, phone, or clientUserId) required per member **Processing:** - Jobs are processed asynchronously - Use the batch job ID to check status via `GET /v2/bulk/job/{bulkJobId}` - Results available as downloadable `.jsonl` file when completed Scopes Required: [segments:all] Default Rate Limit: 100 requests per second - [Remove Bulk Segment Members](https://docs.attentive.com/reference/deletebulksegmentmembers.md): Remove members from a segment in bulk. This endpoint accepts 1 to 10,000 members per request. Members are identified by email, phone number, and/or client user ID. The request is validated, queued for asynchronous processing, and a unique batch job ID is returned for tracking the status. **Request Limits:** - Minimum: 1 member per request - Maximum: 10,000 members per request - At least one identifier (email, phone, or clientUserId) required per member **Processing:** - Jobs are processed asynchronously - Use the batch job ID to check status via `GET /v2/bulk/job/{bulkJobId}` - Results available as downloadable `.jsonl` file when completed Scopes Required: [segments:all] Default Rate Limit: 100 requests per second - [Clear all members from a segment](https://docs.attentive.com/reference/clearsegmentmembers.md): Removes all members from a segment identified by its external ID. This operation is asynchronous — the response indicates that the clear request has been accepted for processing. Only segments created via the Public API can be cleared using this endpoint. Scopes Required: [segments:Write] Default Rate Limit: 100 requests per second - [Bulk Operations](https://docs.attentive.com/reference/bulk-operations.md) - [Retrieve the status of a bulk ingestion job](https://docs.attentive.com/reference/getbulkjobstatus.md): Checks the status of a bulk ingestion job identified by bulkJobId. This endpoint returns the current state of the job (`IN_PROGRESS`, `NEEDS_REVIEW`, `COMPLETED`, or `CANCELLED`) along with the total record count and, once the job has completed successfully, a link to download the results. If the job has completed successfully, the response includes a downloadable link to a `.jsonl` (JSON Lines) file containing a record of each request and its corresponding response. User's can audit results or process downstream outcomes of the bulk operation. You can fetch requests up to 2 weeks old. Scopes Required: No Additional scopes required. Default Rate Limit: 100 requests per second - [Test Authentication](https://docs.attentive.com/reference/test-authentication.md) - [Me](https://docs.attentive.com/reference/getme.md): Make a call to this endpoint to test your unique token that you generate in the Attentive product. - [Access Token](https://docs.attentive.com/reference/access-token.md) - [Access Token](https://docs.attentive.com/reference/createtokenviaauthorizationcode.md): Make a call to this endpoint to exchange a temporary authorization code for an access token. - [Webhooks](https://docs.attentive.com/reference/webhooks.md) - [List webhooks](https://docs.attentive.com/reference/getwebhooks.md): Make an API call to this endpoint to list existing webhooks. - [Create webhook](https://docs.attentive.com/reference/createwebhook.md): Make an API call to this endpoint to subscribe to a webhook. Events are a collection of strings of the following types: * `sms.subscribed` * `sms.sent` * `sms.message_link_click` * `email.subscribed` * `email.unsubscribed` * `email.message_link_click` * `email.opened` * `custom_attribute.set` Event types are case sensitive. All events included will be sent to the URL. - [Delete webhook](https://docs.attentive.com/reference/deletewebhook.md): Make an API call to this endpoint to remove a webhook. - [Update webhook](https://docs.attentive.com/reference/updatewebhook.md): Make an API call to this endpoint to update a webhook - [eCommerce](https://docs.attentive.com/reference/ecommerce.md) - [Product view](https://docs.attentive.com/reference/postproductviewevents.md): Make a call to this endpoint when a user views a product. - [Add to cart](https://docs.attentive.com/reference/postaddtocartevents.md): Make a call to this endpoint when a user adds a product to their shopping cart. - [Purchase](https://docs.attentive.com/reference/postpurchaseevents.md): Make a call to this endpoint when a user generates an order or purchase. - [Offers](https://docs.attentive.com/reference/offers.md) - [Add discount codes](https://docs.attentive.com/reference/createcoupons.md): Note: Once the offer(s) has been created, please reach out to an Attentive team member to enable this API feature for you Make a call to this asynchronous endpoint to create new discount codes in an existing offer.

Validation rules

Sync behavior

Check the status on the offer to monitor progress. If it still says SYNCING, the uploads may not be ready yet. - [Custom Events](https://docs.attentive.com/reference/custom-events.md) - [Custom Events](https://docs.attentive.com/reference/postcustomevents.md): Make a call to this endpoint for any event-based data representing user actions. - [Custom Attributes](https://docs.attentive.com/reference/custom-attributes.md) - [Custom Attributes](https://docs.attentive.com/reference/postcustomattributes.md): Make a call to this endpoint for any attribute-based data. There are no limits to the amount of custom attributes that can be created. Note that you can create net-new properties with this API, however, it cannot be used to create new values for an existing UI-created property name. If a property name is created through the Attentive platform, all possible property values must also be defined in the platform. For example, if a property has possible values of "Adult, Teen, Children's", those are the only values that will be accepted through the API. This does not apply for properties with the type "Custom input", for example: Full Name. Also, please note that the API does not support arrays. For example, attempting to pass an array such as '["chicago", "new york"]' for an attribute like 'favorite_city' will result in a 400 error. **Note : The maximum length for an attribute name is 200 characters.** - [Get Custom Attributes for a User](https://docs.attentive.com/reference/getcustomattributes.md): Make a call to this endpoint to retrieve all custom attribute data associated with a user. You can query this endpoint by either phone or email. **Note: You must include a single query parameter, phone or email. Including both will result in a 400 error.** - [Subscribers](https://docs.attentive.com/reference/subscribers.md) - [Subscribe user](https://docs.attentive.com/reference/addsubscriptions.md): Make a call to this endpoint to opt-in a user to a subscription. Notes: - A legal disclosure is required when a user is opted-in programmatically. - For marketing messages, required [legal language](https://docs.attentivemobile.com/pages/legal-docs/legal-disclosure-language/) must be included. - For transactional messages, you must include a [transactional opt-in unit](https://docs.attentivemobile.com/pages/legal-docs/legal-transactional/). - By default, if a subscription already exists, it will try and record the attempt to create the subscription again. For TEXT subscriptions, this will result in a message being sent to the person indicating that they are already subscribed. - Requests to opt-in subscribers must either contain a) a sign-up source id or b) both a locale and a subscription type. - The unique identifier of a sign-up source can be found in the Sign-up Units tab of the Attentive platform in the ID column. If this value is provided in the request, then this sign-up unit will be used for opting in the user in the request. - Callers of this endpoint have the option to omit `signUpSourceId` and, instead, provide both a `locale` and a `subscriptionType` (see below for field details). Given the locale and subscription type, Attentive will resolve any matching API opt-in units. To opt-in a user to a subscription without a `signUpSourceId` and exclusively based on locale and subscription type, there must be exactly one API sign-up unit that matches the provided locale and subscription type. Conversely, requests that contain a locale and a subscription type that do not have a corresponding sign-up unit or that have multiple matching sign-up units will receive a `400` response and will not opt a user into a subscription. - For users in either France or Italy, in accordance with compliance updates documented [here](https://help.attentive.com/hc/en-us/articles/51464632390804-France-Email-Privacy-Compliance-Update), we set an email pixel tracking consent attribute as part of opting in an email subscriber. This is set by default when the locale of a subscriber is in France or Italy. Due to compliance concerns, are not exposing the capability to set this consent on behalf of the user via our public API subscription endpoints, and the default value is that the subscriber is not consenting to email pixel tracking. If you'd like to expose the capability for the user to opt in to this tracking, you can set up an (email preference collection unit)[https://help.attentive.com/hc/en-us/articles/51708193671444-Setting-Up-Email-Tracking-Consent#h_01KZ9MV94BT1JK0ASB0QE3V8H2] in the Attentive subscribers UI or update the consent attribute in bulk via the [Subscriber Upload in Settings](https://help.attentive.com/hc/en-us/articles/51708193671444-Setting-Up-Email-Tracking-Consent#h_01KZ9MR29EXZFKKGYQQ7WSTPB1). - Phone numbers must be submitted in [e164 format](https://en.wikipedia.org/wiki/E.164). - valid examples: `+19148440001`, `+442071838750`, `+551155256325` - invalid examples: `19148440001`, `+1---914---844---0001`, `1 () 914 844 0001` - [Get subscription eligibility for a user](https://docs.attentive.com/reference/getsubscriptions.md): Make a call to this endpoint to list all subscription types and channels a user is subscribed to. You can query for a subscriber using either their phone number or email. One of the query parameters is required in order to look up a subscriber. As an example, you can use this endpoint to check if a subscriber is eligible to receive SMS or email campaigns, and then send them a message based on that eligibility. - [Unsubscribe subscriptions for a user](https://docs.attentive.com/reference/unsubscribesubscriptions.md): Make a call to this endpoint to unsubscribe a user from a subscription type or channel. If no subscriptions are present in the request, the user is unsubscribed from all subscriptions. If subscriptions are present in the request, the user is unsubscribed from the requested type or channel combination. By default, if a subscription exists, but the user is already unsubscribed, it records the attempt to unsubscribe the subscription again. For TEXT subscriptions, a message is sent to the person indicating that they are unsubscribed. For the user object, the email data point determines which email subscriptions a user has and the phone data point determines which text (or sms) subscriptions a user has. Passing in an email does not locate, nor unsubscribe, a user from any sms subscriptions. Similarly, passing in a phone does not locate, nor unsubscribe, a user from any email subscriptions. - [Product Catalog](https://docs.attentive.com/reference/product-catalog.md) - [Upload Product Catalog](https://docs.attentive.com/reference/postupload.md): Make a call to this endpoint to start sending Attentive your full or partial product catalog. The process starts with a POST to this endpoint, where you will receive a pre-signed AWS S3 URL. You can use any language's http request libraries for uploading a file via HTTP. Here's how to do it with `curl` as an example ``` curl --upload-file ${fileNameLocally} ${presignedURL} ``` and here's an example in Python ```python import requests with open(filepath, 'rb') as f: r = requests.put(upload_url, data=f) ``` [Here are examples from AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html) on how to send the file over in popular programming languages. Note that you aren't interested in the portion of these examples where they are generating the pre-signed URL, but simply the http call to upload the file to the URL. Once your full or partial product catalog begins to upload, the status is updated to `validating` while it's processing and the file is checked for errors. After the upload is validated, the status is updated to `validated`. Once the catalog is saved, the status is updated to `completed`. In cases where there are errors saving the data, Attentive Engineering is notified and will contact you. To ensure there are no validation errors in the file, you can set `validateOnly` parameter to `true` to avoid saving any data. We highly recommend this during your development to get a faster feedback loop on any validation errors as you generate files. If there are no errors returned in the upload response, your product catalog uploaded successfully. - [View Recent Catalog Uploads](https://docs.attentive.com/reference/getuploads.md): Make a call to this endpoint to list recent catalog uploads with their statuses to gain visibility into the ingestion workflow in order of creation. See the POST of this endpoint for details. `Expires` indicates how long you can wait before uploading the product catalog file. If the catalog upload expires, then we will no longer process the file that you upload and you will need to initiate a new catalog upload. - [Lookup Product Catalog Ingestion](https://docs.attentive.com/reference/lookupupload.md): Making a GET request with the uploadID from your original catalog upload POST will give you the updated information on how the upload is progressing. You can also use the list endpoint as well to retrieve the same data. Please see the POST of `/product-catalog/uploads` for more detail. - [Privacy Request](https://docs.attentive.com/reference/privacy-request.md) - [Add a deletion request](https://docs.attentive.com/reference/adddeleterequest.md): Make a call to this endpoint to create a new privacy deletion request. This will delete a subscriber within thirty days, provided the call was successful. Use the GET endpoint with the id returned to confirm deletion. - [Get a CCPA delete request by Id](https://docs.attentive.com/reference/getdeleterequest.md) - [Identity](https://docs.attentive.com/reference/identity.md) - [Add a client user identifier or custom identifier(s) to a user](https://docs.attentive.com/reference/identify.md): Make a call to this endpoint to associate a client user identifier or custom identifier(s) with other identifiers. A client user or custom identifier needs to be accompanied by at least one other identifier of the following types: phone, email, shopify id, klaviyo id, client user identifier, or custom identifier. - [Introduction to Attentive's GraphQL API](https://docs.attentive.com/reference/graphql-introduction.md) - [Test Authentication](https://docs.attentive.com/reference/test-authentication-graphql.md) - [Get Installed Application](https://docs.attentive.com/reference/get-installed-application.md) - [Subscribers](https://docs.attentive.com/reference/subscribers-graphql.md) - [Get Subscription Eligibility for a User](https://docs.attentive.com/reference/get-subscription-eligibility.md) - [Subscribe User](https://docs.attentive.com/reference/subscribe.md) - [Unsubscribe User](https://docs.attentive.com/reference/unsubscribe.md) - [Custom Events](https://docs.attentive.com/reference/custom-events-graphql.md) - [Custom Events](https://docs.attentive.com/reference/graphql-custom-events.md) - [Custom Attributes](https://docs.attentive.com/reference/custom-attributes-graphql.md) - [Custom Attributes](https://docs.attentive.com/reference/graphql-custom-attributes.md) - [Webhooks](https://docs.attentive.com/reference/webhooks-graphql.md) - [Get webhooks](https://docs.attentive.com/reference/webhooks-get-all.md) - [Get a webhook](https://docs.attentive.com/reference/webhooks-get.md) - [Create a webhook](https://docs.attentive.com/reference/webhooks-create.md) - [Update a webhook](https://docs.attentive.com/reference/webhooks-update.md) - [Disable a webhook](https://docs.attentive.com/reference/webhooks-delete.md)