Documentation Index
Fetch the complete documentation index at: https://docs.snappy.com/llms.txt
Use this file to discover all available pages before exploring further.
Field Projection
To optimize performance and reduce payload size, the Snappy API allows you to control exactly which data fields are returned in a response. This is particularly useful for mobile integrations or high-volume data processing where bandwidth and parsing speed are critical.
The fields Parameter
You can shape your response by adding the fields query parameter to any GET request.
| Value | Description |
|---|
| Comma-separated list | Returns only the specific fields requested (e.g., fields=id,name,status). |
full | Returns every available field for the object, bypassing the default set. |
| Default | If omitted, Snappy returns a predefined “common” set of fields (usually id and name). |
How to Use Projection
If you are fetching a list of Campaigns but only need their unique IDs and names to populate a dropdown menu, your request would look like this:
GET /v2/campaigns?fields=id,name
Standard Response:
{
"id": "com_12345",
"name": "Holiday 2024 Wellness"
}
Constraints & Rules
Parent Object Only: Currently, field projection only applies to the primary (parent) object in the response. You cannot project fields on nested objects within the same parameter.
- No Spaces: Ensure your list is comma-separated with no spaces (e.g.,
id,name,type).
- Case Sensitivity: Field names must match the exact casing found in the API Reference.
- Service Defaults: Default fields vary by service. Check the specific endpoint documentation for the default field set.
Expanding Objects
To minimize the number of API calls your integration needs to make, Snappy supports Object Expansion. This allows you to request that certain IDs in a response be replaced with the full data object they represent.
The expand Parameter
Use the expand query parameter to specify which related objects should be included in the response. You can expand multiple objects by passing an array of strings.
| Parameter | Type | Description |
|---|
expand[] | Array | A list of expandable objects to be returned as full JSON objects instead of just IDs. |
How it Works
By default, many Snappy objects reference related entities by their ID. For example, a Gift object might only contain a product_id.
Default Response:
{
"id": "gft_abcd123",
"product_id": "prd_98765",
"status": "sent"
}
expand[]=product to your request, the product_id is replaced by the full Product object.
Request: GET /v2/gifts/gft_abcd123?expand[]=product
Expanded Response:
{
"id": "gft_12345",
"product": {
"id": "prd_12345",
"name": "Luxury Wellness Set",
"description": "A curated set of wellness items...",
"value": 50.00
},
"status": "sent"
}
Common Expandable Objects
product: Pull in full product descriptions, images, and values.recipient: Include full contact details for the recipient.campaign: Get the settings and branding rules for the associated campaign.
Best Practices
- Performance: Only expand the objects your application actually needs. Expanding too many fields can increase response latency.
- Compatibility: Use expansion to reduce client-side logic—especially in mobile apps or low-latency environments.
- Combine with Projection: You can use
expand alongside fields to get the full object but only the specific sub-fields you require.
To maintain performance and stability, Snappy paginates responses that return a large number of items. By default, lists are limited to 100 items per request, but you can iterate through the entire dataset using the skip and limit parameters.
Parameters
Include these as query parameters in your GET requests:
| Parameter | Description | Default | Max |
|---|
limit | The number of results to return per page. | 100 | 100 |
skip | The number of items to “skip” or offset from the start of the list. | 0 | - |
How to Paginate
To move through pages, increment the skip value by the limit used in your previous request.
- Page 1:
limit=100&skip=0
- Page 2:
limit=100&skip=100
- Page 3:
limit=100&skip=200
The general formula for any given page is: skip = (page_number - 1) * limit
Identifying the End of Data
Your integration should continue fetching pages until one of the following “stop conditions” is met:
Stop Conditions:
- The number of items in the
results array is less than your limit.
- The
results array returned is empty.
limit=100 and receive 85 items, you have reached the final page. If you receive 100 items, assume there is more data and make a subsequent call with skip=100.
Metadata allows you to attach custom key-value pairs to Snappy objects, such as Gifts. This feature is essential for mapping Snappy events to your internal systems or storing supplemental data that isn’t captured by our standard API fields.
Any metadata you provide during a resource’s creation will be persisted and included in all subsequent GET responses and Webhook notifications associated with that resource.
Operational Constraints
| Attribute | Constraint |
|---|
| Max Key-Value Pairs | 50 pairs per object |
| Key Requirements | Alphanumeric, max 40 characters |
| Value Requirements | Alphanumeric, max 500 characters |
Implementation Example
{
"campaignId": "cmp_12345",
"recipient": {
"email": "developer@example.com"
},
"metadata": {
"internal_employee_id": "EMP-9982",
"salesforce_opp_id": "0061a00000abc123",
"cost_center": "Marketing_Q4"
}
}
Global Standards
Snappy uses the ISO 8601 standard for all date and time fields. All timestamps are returned in UTC.
- Format:
YYYY-MM-DDTHH:mm:ss.sssZ
- Example:
2026-04-13T12:00:00.000Z
Error Structure
When a request cannot be processed, Snappy returns a flat error object alongside the relevant HTTP status code. The structure differs slightly between validation errors (HTTP 400) and all other errors.
Validation errors (HTTP 400):
{
"path": "campaignId",
"errorCode": "INVALID_REQUEST",
"message": "The campaignId provided does not exist."
}
{
"status": 404,
"errorCode": "NOT_FOUND",
"message": "The resource you requested could not be found."
}
| Field | Type | Description |
|---|
path | string | (400 only) The request parameter or body field that caused the validation error. |
status | number | (Non-400 errors) The HTTP status code. |
errorCode | string | A short identifier for the error type (e.g., INVALID_REQUEST, NOT_FOUND). See Error Handling for the full list. |
message | string | A developer-friendly explanation of the error. |
