Formation API (V1.0)

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.

Authentication

api_key

Security Scheme Type API Key
Header parameter name: x-api-key

Transaction

Transactions progress customers offers and trigger the issuance of rewards

Send Formation Transactions

Send transactions to Formation to progress customer offers.

Request
Security:
Request Body schema: application/json
Array ([ 1 .. 100 ] items)
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.

Responses
200

Your batch of transactions has been accepted and will be processed

400

There are one or more malformed transaction payloads. You must inspect and correct the batch before resubmitting.

403

Sender not recognized. Unable to authenticate or process data.

413

Your request is too large and exceeds the maximum payload size of 1MB. Split your batch of transactions and try again.

500

Internal server error. Please try resubmitting the batch.

post/v1/transaction
Request samples
application/json
[
  • {
    }
]

Activation

Activations allow customer transactions to progress their offers

Offer activation endpoint

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.

Request
Security:
Request Body schema: application/json
customer_id
required
string (customer_id) <= 64 characters

The customer ID you used to target your customer in an audience.

activation_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.

activation_utc_datetime
required
string <date-time>

UTC date and time for the offer activation 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.

offer_id
required
string

The customer's assigned Formation offer id, found in Status or Connector payloads.

Responses
200

The customer's offer will be successfully activated

400

Your payload has one or more errors present. Please fix and resubmit.

403

Sender not recognized. Unable to authenticate or process data.

500

Internal server error. Please try resubmitting requests.

post/v1/activation
Request samples
application/json
{
  • "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"
}

Status

Ask Formation for the offers that a customer currently has active as well as their progress.

Retrieve the list of active offers for a customer

Returns a list of offers that are currently active for a CustomerID

Request
Security:
path Parameters
CustomerID
required
string (customer_id) <= 64 characters

ID of the customer that you want to retrieve status for

Responses
200

The customer was found and any active offers are returned

400

Your request could not be completed as made

403

Sender not recognized.

404

customer_id was not found

500

Internal server error. Please try again later.

get/status/{CustomerID}
Request samples
curl -i -X GET \
  'https://api.formation.ai/status/{CustomerID}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Action

Actions progress customer offers that ask customers to complete activities that are not purchases

Send Formation non-transaction events

Send Formation actions to progress multi-action offer steps that are not purchases

Request
Security:
Request Body schema: application/json
Array ([ 1 .. 500 ] items)
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.

Responses
200

Your batch of actions has been accepted and will be processed

400

There are one or more malformed action payloads. You must inspect and correct the batch before resubmitting.

403

Sender not recognized. Unable to authenticate or process data.

413

Your request is too large and exceeds the maximum payload size of 1MB. Split your batch of actions and try again.

500

Internal server error. Please try resubmitting the batch.

post/v1/action
Request samples
application/json
[
  • {
    }
]