Access the data via the API

Prerequisites

Before you begin, ensure you have:

• The Fospha client ID for your brand
• A valid access token (see Retrieve a token)

If you do not have the Fospha client ID yet, please contact Fospha support.

Retrieval Flow

Please contact support to get an indicative time when data is ready each day.

1. First call the marketingDataReadiness endpoint to check if the data is ready for you to download.
2. If the data is not ready, wait a few minutes and try again.
3. If the data is ready, download it using the marketingRecords and/or marketingAggregate endpoints.

Authentication

All queries require a valid access token in the header: Authorization: Bearer {TOKEN}.

The API supports granular permissions based on markets and data sources. Only request as much data access as your application needs.

curl -X POST \
  https://api.{REGION}.fospha.com/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -d '{
    "query": "{YOUR_QUERY}"
  }'

note

Replace {REGION} with your country code; for example, use uk for the United Kingdom or us for the United States.

Understanding the Schema

In the GraphQL schema, fields marked with ! are required:

• For inputs: You must provide a value (e.g., clientId: ID! means clientId is mandatory).
• For outputs: The server guarantees a value will be returned (e.g., recordId: ID! will never be null).

Endpoints and Queries

GraphQL queries are executed by sending POST HTTP requests to the endpoint: https://api.{REGION}.fospha.com/graphql.

Defaults

If you omit an optional argument, the API applies the following defaults.

Argument	Default	Notes
currency	EUR	Affects every monetary field. Pass explicitly to match your reporting currency.
pagination.pageSize	1000	Minimum 1000, maximum 5000. See Limits below.
pagination.page	1	First page.
sort	[{ field: DATE_DAY, direction: DESC }]	Most recent dates first.
filter	unset (no filtering)	Returns all records your credentials can access.

Limits

The API has several limits to ensure fair usage and optimal performance.

Metrics Limits

For aggregate queries:

• Requesting a TOTAL_ field requires adding the corresponding metric in the parameters.

Rate Limits

• 1000 requests per 5 minutes per IP
• Additional limits may apply and are subject to change

Data Range Limits

• Maximum 90 days per request for date ranges
• Make multiple requests for longer periods

Note: dates are inclusive.

Pagination Limits

• Minimum page size: 1000
• Maximum page size: 5000

Sorting Limits

For aggregate queries:

• A maximum of 2 sort entries per query

Status and Error Codes

All API queries return HTTP status codes with additional information:

• 200 OK: GraphQL returns 200 OK for most responses, including queries with errors; check the errors field in the response for query-specific issues.
• 401 Unauthorized: Invalid or expired access token; refresh your token using your client credentials.
• 403 Forbidden: Valid token but insufficient permissions for the requested data.
• 429 Too Many Requests: Rate limit exceeded, wait before making additional requests.

Support

For OAuth setup issues or credential requests, please visit our support portal at servicedesk.fospha.com.

When reporting an issue, please include:

• The payload of the request that caused the error (never share the token)
• Your app_client_id (never share your app_client_secret)
• Your fospha_client_id
• The full error message received
• The timestamp (including timezone) when the error occurred
• Any other relevant context (for example, API endpoint and request type)