Download OpenAPI specification:Download
The Formation API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Activations, transactions and actions progress customers offers and trigger the issuance of rewards
Send transactions to Formation to progress customer offers.
| customer_id required | string (customer_id) <= 64 characters The customer ID you used to target your customer in an audience. |
| transaction_id required | string <= 64 characters Unique transaction event identifier. This is how Formation tells events apart. We use transaction IDs to identify duplicates and avoid double awarding progress or rewards. |
| transaction_local_datetime required | string <local-date-time> (Local Date Time) ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d... Customer's local date and time for transaction event. Use the format YYYY-MM-DDT00:00. For example, an event that happens on January 12, 2025 at 7 a.m. local time would be formatted as 2025-01-12T07:00. |
| transaction_utc_datetime required | string <date-time> UTC date and time for transaction event. Use the format YYYY-MM-DDT00:00Z. For example, an event that happens on January 12, 2025 at 7 a.m. UTC would be formatted as 2025-01-12T07:00Z. |
| transaction_total_spend required | integer <int64> >= 0 Customer's total transaction spend as cents. Any non-rewardable tender such as coupons should not be included in this value if you do not want to progress an offer with it. |
required | Array of objects (LineItem) [ 1 .. 500 ] items |
object (Empty Schema) A dictionary of string:string pairs. Formation does not inspect, modify, or make decisions based on attribute fields. This field can be useful for carrying details through the outputs of the Formation platform. |
Your batch of transactions has been accepted and will be processed
There are one or more malformed transaction payloads. You must inspect and correct the batch before resubmitting.
Sender not recognized. Unable to authenticate or process data.
Your request is too large and exceeds the maximum payload size of 1MB. Split your batch of transactions and try again.
Internal server error. Please try resubmitting the batch.
[- {
- "customer_id": "8b896428-ac34-4911-98af-3d2e6266f60e",
- "transaction_id": "b48c8bbc-bcb8-11eb-8529-0242ac130003",
- "transaction_local_datetime": "2021-01-01T00:01:01",
- "transaction_utc_datetime": "2021-01-01T07:01:01Z",
- "transaction_total_spend": 12477,
- "line_items": [
- {
- "item_sku": "94040",
- "item_price": 99,
- "item_quantity": 0.98,
- "item_spend": 9702
}, - {
- "item_sku": "94467",
- "item_price": 299,
- "item_quantity": 3.56,
- "item_spend": 800
}, - {
- "item_sku": "587493038382",
- "item_price": 199,
- "item_quantity": 2,
- "item_spend": 398
}
]
}
]Send Formation actions to progress multi-action offer steps that are not purchases
| customer_id required | string (customer_id) <= 64 characters The customer ID you used to target your customer in an audience. |
| action_local_datetime required | string <local-date-time> ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d... Customer's local date and time for the action. Use the format YYYY-MM-DDT00:00. For example, an action that happens on January 12, 2025 at 7 a.m. local time would be formatted as 2025-01-12T07:00. |
| action_utc_datetime required | string <date-time> UTC date and time for the action. Use the format YYYY-MM-DDT00:00Z. For example, an action that happens on January 12, 2025 at 7 a.m. UTC would be formatted as 2025-01-12T07:00Z. |
| action_id required | string <= 64 characters A key that uniquely identifies the action a customer took |
| event_id | string <= 64 characters A key that uniquely identifies this instance of this customer taking this action. This identifier will be used to deduplicate. |
Your batch of actions has been accepted and will be processed
There are one or more malformed action payloads. You must inspect and correct the batch before resubmitting.
Sender not recognized. Unable to authenticate or process data.
Your request is too large and exceeds the maximum payload size of 1MB. Split your batch of actions and try again.
Internal server error. Please try resubmitting the batch.
[- {
- "customer_id": "128b896428-ac34-4911-98af-3d2e6266f60e34567",
- "action_local_datetime": "2021-01-01T00:01:01",
- "action_utc_datetime": "2021-01-01T07:01:01Z",
- "action_id": "Action1",
- "event_id": "C1C8A713-666B-427D-9155-0E2C866515A1"
}
]Updates offer state to active based on customer action. Typically triggered as the result of user opting in to an offer through the channel they received the offer.
The customer's offer will be successfully activated
Your payload has one or more errors present. Please fix and resubmit.
Sender not recognized. Unable to authenticate or process data.
Internal server error. Please try resubmitting requests.
{- "customer_id": "128b896428-ac34-4911-98af-3d2e6266f60e34567",
- "activation_local_datetime": "2021-01-01T00:01:01",
- "activation_utc_datetime": "2021-01-01T07:01:01Z",
- "offer_id": "229f7d6d-21ed-4b09-836f-b8c032cac523"
}Returns a list of offers that are currently active for a CustomerID
The customer was found and any active offers are returned
| customer_id | string (customer_id) <= 64 characters The customer ID you used to target your customer in an audience. |
| offer_type | string Enum: "single_purchase" "single_category_purchase" "week_streak" "multi_action" "cumulative_purchase" |
| start_time | string <local-date-time> (Local Date Time) ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d... Customer's local date and time for transaction event. Use the format YYYY-MM-DDT00:00. For example, an event that happens on January 12, 2025 at 7 a.m. local time would be formatted as 2025-01-12T07:00. |
| end_time | string <local-date-time> (Local Date Time) ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d... Customer's local date and time for transaction event. Use the format YYYY-MM-DDT00:00. For example, an event that happens on January 12, 2025 at 7 a.m. local time would be formatted as 2025-01-12T07:00. |
| unique_offer_id | string |
| status | string (OfferStatus) Enum: "eligible" "active" "completed" |
object | |
object (Redemptions) | |
object (Reward) | |
object (SummaryReward) | |
| tags | object (Tags) A set of Formation-generated k-v pairs for hosted content, or those entered in the UI at campaign launch. |
Your request could not be completed as made
Sender not recognized.
customer_id was not found
Internal server error. Please try again later.
curl -i -X GET \ 'https://api.formation.ai/status/{CustomerID}' \ -H 'x-api-key: YOUR_API_KEY_HERE'
[- {
- "customer_id": "string",
- "offer_type": "single_purchase",
- "start_time": "string",
- "end_time": "string",
- "unique_offer_id": "string",
- "status": "eligible",
- "steps": {
- "step_1": {
- "step_type": "custom_action",
- "step_status": "eligible",
- "conditions": {
- "action": "string"
}
}, - "step_2": {
- "step_type": "custom_action",
- "step_status": "eligible",
- "conditions": {
- "action": "string"
}
}
}, - "redemptions": {
- "type": "limited",
- "limit": 0,
- "total_redemptions": 0,
- "total_reward": 0
}, - "offer_reward": {
- "reward_value": "string",
- "reward_currency": "string",
- "reward_type": "fixed",
- "reward_id": "string"
}, - "total_reward": {
- "reward_value": "string",
- "reward_currency": "string",
- "reward_type": "string"
}, - "tags": {
- "user_entered_key_1": "user_entered_value_1",
- "user_entered_key_2": "user_entered_value_2"
}
}
]Disassociates a customer from their purchase history in the platform as well as from any active offers
The customer ID you used to target your customer in an audience.
The customer(s) have been forgotten
Your payload has one or more errors present. Please fix and retry.
Sender not recognized. Unable to authenticate or process data.
Internal server error. Please try resubmitting your request.
[- "128b896428-ac34-4911-98af-3d2e6266f60e34567"
]