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