Cint Intelligent Calendar API
Select the best times for launching your Target Groups. Use before feasibility to optimise fill and time in field.
OpenAPI Specification
openapi: 3.0.3
info:
title: Demand Accounts Intelligent Calendar API
description: 'Cint''s demand ordering API is REST oriented. It has predictable resource based URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Error responses are also JSON-encoded and follow a standard format, providing a unique error ID and detailed information about what went wrong.
Authentication is handled via bearer tokens passed in the `Authorization` header. All requests must also include a `Cint-API-Version` header with a date in `YYYY-MM-DD` format to specify the desired API version. Depending on the version you use, endpoint behavior may differ as we improve our API with every version release.
While many operations work on a single object per request, the demand ordering API also provides asynchronous batch endpoints for performing bulk updates efficiently on certain resources. For safety, `POST` requests support an `Idempotency-Key` header to allow for safe retries without accidentally performing the same operation twice.
'
version: '2025-12-18'
servers:
- description: Production server
url: https://api.cint.com/v1
security:
- BearerAuth: []
tags:
- name: Intelligent Calendar
description: Select the best times for launching your Target Groups. Use before feasibility to optimise fill and time in field.
paths:
/demand/intelligent-calendar/suggest-days:
parameters:
- $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
post:
summary: Suggest the required fielding time for a target group
description: Suggests the optimal number of days required to field a target group based on its specifications. You can use this endpoint to estimate fielding time before creating a target group. You'll need to provide details like the locale, price, length of interview (LOI), incidence rate (IR), and desired number of completes.
operationId: suggest_days
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SuggestDaysRequest'
example:
locale: eng_us
price:
value: '2.50'
currency_code: USD
length_of_interview: 15
incidence_rate": 0.25
completes: 500
collects_pii: false
responses:
'200':
description: The suggested number of days was calculated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SuggestDaysResponse'
example:
days: 14
headers:
traceparent:
$ref: '#/components/headers/Traceparent'
tracestate:
$ref: '#/components/headers/Tracestate'
'400':
$ref: '#/components/responses/Error_BadRequest'
'401':
$ref: '#/components/responses/Error_Unauthorized'
'500':
$ref: '#/components/responses/Error_Internal'
tags:
- Intelligent Calendar
/demand/intelligent-calendar/suggest-time-range:
parameters:
- $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
get:
summary: Suggests an optimal fielding time range for a locale
description: 'Suggests an optimal time range to field a target group in a specific locale, taking into account local holidays and respondent activity patterns.
How to specify a time range:
* To get a suggestion for a specific duration starting from now, provide the `days` parameter.
* To get a suggestion within a specific date window, provide both the `start` and `end` parameters.
'
operationId: suggest_time_range
parameters:
- name: days
in: query
description: The number of days to field the target group. Use this parameter OR both `start` and `end`.
required: false
schema:
type: integer
minimum: 1
example: 10
- name: start
in: query
description: The start date for the fielding window (RFC3339 format). Use this parameter in conjunction with `end`, OR only use `days`.
required: false
schema:
type: string
format: date-time
example: '2023-01-01T23:00:00.000Z'
- name: end
in: query
description: The end date for the fielding window (RFC3339 format). Use this parameter in conjunction with `start`, OR only use `days`.
required: false
schema:
type: string
format: date-time
example: '2023-01-31T23:00:00.000Z'
- name: locale
in: query
description: Locale code.
schema:
$ref: '#/components/schemas/LocaleCode'
responses:
'200':
description: The suggested time range was calculated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SuggestedTimeRangeResponse'
example:
start: '2024-09-03T08:00:00.000Z'
end: '2024-09-17T22:00:00.000Z'
holidays:
- date: '2024-09-02'
name: Labor Day
respondent_rate: 0.7
completes_rate: 0.65
timezone: America/New_York
headers:
traceparent:
$ref: '#/components/headers/Traceparent'
tracestate:
$ref: '#/components/headers/Tracestate'
'400':
$ref: '#/components/responses/Error_BadRequest'
'401':
$ref: '#/components/responses/Error_Unauthorized'
'500':
$ref: '#/components/responses/Error_Internal'
tags:
- Intelligent Calendar
components:
schemas:
Tracestate:
type: string
description: 'The tracestate header provides additional contextual information to the traceparent header. This enriches the tracing context and offers more fine-grained control
Note: This field is optional and will be automatically generated by the service if not provided in the request. The generated value will be included in the response header.'
example: ot=foo:bar;k1:13
SuggestDaysResponse:
type: object
description: The suggested number of days required for fielding.
properties:
days:
type: integer
description: The suggested number of days required to field the target group.
example: 10
Error:
type: object
description: The standard error object returned for all failed API requests.
required:
- object
- detail
properties:
id:
type: string
format: uuid
description: A unique identifier for this specific error instance.
object:
type: string
description: A short informative string identifying the type of the error
pattern: ^([a-z]*_)*([a-z]*)$
detail:
type: string
description: An error message provides a concise overview of the cause of the error.
invalid_params:
type: array
nullable: true
description: An optional field containing a list of invalid parameters may be presented in validation errors for additional information.
items:
$ref: '#/components/schemas/InvalidParam'
SuggestDaysRequest:
type: object
description: The set of parameters required to generate a fielding time suggestion.
required:
- locale
- price
- length_of_interview
- incidence_rate
- completes
properties:
locale:
$ref: '#/components/schemas/LocaleCode'
collects_pii:
type: boolean
description: Indicates whether or not the target group collects Personally Identifiable Information (PII).
example: true
price:
description: The desired Cost Per Interview for the filling goal suggestion.
allOf:
- $ref: '#/components/schemas/MonetaryAmountRequestModel'
length_of_interview:
type: integer
description: The expected median length of the interview, in minutes.
minimum: 1
maximum: 45
example: 5
incidence_rate:
type: number
description: The expected incidence rate (IR) of the target audience, expressed as a decimal (e.g., 0.5 for 50%).
minimum: 0
maximum: 1
example: 0.5
completes:
type: integer
description: The desired number of completed interviews.
minimum: 1
example: 1000
SuggestedTimeRangeResponse:
type: object
description: A suggested time range for fielding, including holiday and timezone information.
properties:
start:
type: string
description: Starting timestamp of the suggested time range.
format: date-time
example: '2023-01-01T23:00:00.000Z'
end:
type: string
description: Ending timestamp of the suggested time range.
format: date-time
example: '2023-01-10T23:00:00.000Z'
holidays:
type: array
description: List of holidays in the suggested time range.
items:
type: object
properties:
date:
type: string
description: The date of the holiday in YYYY-MM-DD format.
example: '2023-01-01'
name:
type: string
description: The name of the holiday.
example: New Year's Day
respondent_rate:
type: number
format: double
description: The projected respondent activity rate on this day, relative to a normal day (1.0).
example: 0.65
completes_rate:
type: number
format: double
description: The projected survey completion rate on this day, relative to a normal day (1.0).
example: 0.54
timezone:
type: string
description: The IANA time zone identifier for the suggested range (e.g., "Europe/London").
example: Europe/London
LocaleCode:
type: string
description: Unique text code of the locale.
example: eng_us
MonetaryAmountRequestModel:
type: object
description: Represents a monetary value, including the amount and its currency.
properties:
value:
type: string
description: The monetary value, represented as a string to maintain precision.
example: '2.7352'
currency_code:
$ref: '#/components/schemas/CurrencyCode'
Traceparent:
type: string
description: 'The traceparent header carries essential trace context information. This includes the trace ID and parent span ID as defined by the W3C trace context specification. It is used to pinpoint the position of an incoming request within the trace graph, facilitating the tracking of distributed operations.
Note: This field is optional and will be automatically generated by the service if not provided in the request. The generated value will be included in the response header.'
example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
InvalidParam:
type: object
description: Describes a single invalid parameter in a request.
properties:
name:
type: string
description: The name of the parameter that failed validation.
reason:
type: string
description: A short explanation of why the parameter was invalid.
required:
- name
- reason
CurrencyCode:
type: string
description: The three-letter ISO 4217 currency code, in uppercase. The code must correspond to a currency supported by Cint Exchange.
example: USD
headers:
Traceparent:
description: The `traceparent` header carries the trace ID and parent span ID, as defined by the W3C Trace Context specification. It's used to trace a single request as it moves through multiple services.
required: false
schema:
$ref: '#/components/schemas/Traceparent'
Tracestate:
description: The `tracestate` header complements the `traceparent` header by carrying vendor-specific trace information. This allows different services to add their own data to a trace.
required: false
schema:
$ref: '#/components/schemas/Tracestate'
responses:
Error_BadRequest:
description: A request is not valid and can't be processed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
id: 9e278238-d011-4e05-8327-1ce1d5d26254
object: bad_request_error
detail: Expected field 'foo' is missing.
Error_Unauthorized:
description: A request is unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
id: 1dcf0f40-f0d1-4cf6-8c00-c3d019d32faf
object: authorization_error
detail: no valid authorization provided for this operation
Error_Internal:
description: A request failed due to an internal error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
id: d94b8bb2-a540-4a91-9c05-2aa3ae9a5e1e
object: unexpected_internal_error
detail: an internal error has led to the failure of this operation
parameters:
CintAPIVersion-2025-12-18:
name: Cint-API-Version
in: header
required: true
schema:
type: string
example: 2025-12-18
description: 'This header is MANDATORY for all API requests. The API version format is `YYYY-MM-DD`.
'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer token used for authentication and authorization. See [Authentication Process](https://developer.cint.com/en/guides#authentication-process) documentation for more information.
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: API Key Authentication