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

Coming soon: Our Transactions developer documents are being finalized. Check back soon for updates.

Send Formation Transactions

Send transactions to Formation to progress customer offers.

Request

Security:

api_key

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

Payload
curl

application/json

[{"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
}
]
}
]

Activation

Activations allow customer transactions to progress their offers

Coming soon: Our Activations developer documents are being finalized. Check back soon for updates.

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:

api_key

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

Payload
curl

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:

api_key

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

curl -i -X GET \
  'https://api.formation.ai/status/{CustomerID}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

[{"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"
}
}
},
"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": [{"tag_name": "string"
}
]
}
]

Action

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

Coming soon: Our Actions & multi-action offer documents are being finalized. Check back soon for updates.

Send Formation non-transaction events

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

Request

Security:

api_key

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

Payload
curl

application/json

[{"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"
}
]