openapi: 3.2.0
info:
  title: cdp-api Funnels API
  description: All of the CDP APIs are organized around REST - if you've interacted with a RESTful API already, many of the concepts will be familiar to you. All API calls to CDP API should be made to the following endpoints depending on the [region](https://docs.treasuredata.com/display/public/PD/Sites+and+Endpoints#SitesandEndpoints-Endpoints). For historical reasons there are REST API endpoints and JSON:API endpoints. JSON:API endpoints are located under "/entities".
  termsOfService: https://www.treasuredata.com/terms/
  version: 1.0.0
servers:
- url: https://api-cdp.treasuredata.com
- url: https://api-cdp.treasuredata.co.jp
- url: https://api-cdp.eu01.treasuredata.com
- url: https://api-cdp.ap02.treasuredata.com
- url: https://api-cdp.ap03.treasuredata.com
tags:
- name: Funnels
  description: One of the challenges of targeting customers with relevant campaigns is understanding where they are in their customer journey. Many organizations use the traditional marketing funnel to understand where their customers are in the buying process. Knowing where customers are in the marketing funnel allows organizations to create campaigns and analyze customer behaviors that are specific to individual customers or customer groups. Being able to use all available customer data to accurately identify exactly in which stage customers are in gives marketers a clear advantage. <br> <br> Treasure Data offers Funnels, a premium subscription feature in Audience Studio, which provides this advantage to its users. Funnels make it easier for marketers to see exactly where their customers are in the buying process, allowing them to create more customer-tailored marketing campaigns using multi-channel activations.<br> <br> Funnels enables marketers to create and customize a marketing funnel with up to eight stages in the Audience Studio to reflect the exact buying experience of their customers. After the Funnel stages have been created, marketers can further analyze and refine the stages and activate specific stages for campaigns.
paths:
  /audiences/{audienceId}/funnels:
    x-external: true
    get:
      tags:
      - Funnels
      summary: List of funnels
      description: Retrieves a list of funnels associated with a parent segment identifier and its stages.
      operationId: funnels#index
      parameters:
      - name: audienceId
        in: path
        description: Master Segment ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: succeeded to get
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Funnel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - TdApikeyAuth: []
    post:
      tags:
      - Funnels
      summary: Create funnel (legacy)
      description: Create a new funnel, assign it a name and description matching your business needs. <br> <br> <br> _This endpoint is for Audience Studio legacy. For the latest Audience Studio, contact your Customer Success Representative._
      operationId: funnels#create
      parameters:
      - name: audienceId
        in: path
        description: Master Segment ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        description: Funnel parameters to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FunnelParameters'
        required: true
      responses:
        '200':
          description: Succeeded to create funnel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Funnel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - TdApikeyAuth: []
  /audiences/{audienceId}/funnels/{funnelId}:
    x-external: true
    get:
      tags:
      - Funnels
      summary: Retrieve funnel by ID
      description: Search and find a specific funnel by its identifier. <br> <br> <br>
      operationId: funnels#show
      parameters:
      - name: audienceId
        in: path
        description: Master Segment ID
        required: true
        schema:
          type: integer
          format: int64
      - name: funnelId
        in: path
        description: Funnel ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: succeeded to get
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Funnel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - TdApikeyAuth: []
    put:
      tags:
      - Funnels
      summary: Update funnel (legacy)
      description: Update a funnel. <br> <br> <br> _This endpoint is for Audience Studio legacy. For the latest Audience Studio, contact your Customer Success Representative._
      operationId: funnels#update
      parameters:
      - name: audienceId
        in: path
        description: Master Segment ID
        required: true
        schema:
          type: integer
          format: int64
      - name: funnelId
        in: path
        description: Funnel ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        description: Funnel parameters to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FunnelParameters'
        required: true
      responses:
        '200':
          description: Succeeded to update funnel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Funnel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - TdApikeyAuth: []
    delete:
      tags:
      - Funnels
      summary: Delete funnel (legacy)
      description: Delete a funnel. <br> <br> <br> _This endpoint is for Audience Studio legacy. For the latest Audience Studio, contact your Customer Success Representative._
      operationId: funnels#delete
      parameters:
      - name: audienceId
        in: path
        description: Master Segment ID
        required: true
        schema:
          type: integer
          format: int64
      - name: funnelId
        in: path
        description: Funnel ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Succeeded to delete funnel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Funnel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - TdApikeyAuth: []
  /audiences/{audienceId}/funnels/{funnelId}/clone:
    x-external: true
    post:
      tags:
      - Funnels
      summary: Clone funnel
      description: Make a copy of a funnel.
      operationId: funnels#clone
      parameters:
      - name: audienceId
        in: path
        description: Master Segment ID
        required: true
        schema:
          type: integer
          format: int64
      - name: funnelId
        in: path
        description: Funnel ID to be cloned
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        description: Funnel parameters to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FunnelCloneParameters'
        required: true
      responses:
        '200':
          description: Succeeded to update funnel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Funnel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - TdApikeyAuth: []
  /audiences/{audienceId}/funnels/{funnelId}/statistics:
    x-external: true
    get:
      tags:
      - Funnels
      summary: Retrieve the population statistics of a funnel and its funnel stages
      description: Retrieve the population history of a funnel. The history is returned per day and those days are calculated in the timezone of the audience.
      operationId: funnels#statistics
      parameters:
      - name: audienceId
        in: path
        description: Audience ID of the funnel
        required: true
        schema:
          type: integer
          format: int64
      - name: funnelId
        in: path
        description: ID of funnel to return
        required: true
        schema:
          type: integer
          format: int64
      - name: from
        in: query
        description: from date
        schema:
          type: string
          format: date
          example: '2019-01-01'
      - name: to
        in: query
        description: to date (inclusive)
        schema:
          type: string
          format: date
          example: '2019-04-30'
      - name: limit
        in: query
        description: number of days to fetch funnel statistics
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: array of tuple of statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunnelStatistic'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - TdApikeyAuth: []
  /entities/funnels:
    x-external: true
    post:
      tags:
      - Funnels
      summary: Create funnel
      description: Create a funnel.
      requestBody:
        content:
          application/vnd.treasuredata.v1+json:
            schema:
              $ref: '#/components/schemas/EntitiesFunnelCreateRepresentation'
      responses:
        '200':
          description: Created funnel
          content:
            application/vnd.treasuredata.v1+json:
              schema:
                $ref: '#/components/schemas/EntitiesGetFunnelJsonApiResponse'
  /entities/funnels/{id}:
    x-external: true
    get:
      tags:
      - Funnels
      summary: Retrieve funnel by ID
      description: Retrieve a funnel by ID.
      parameters:
      - name: id
        in: path
        description: Funnel ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Returns a funnel by ID
          content:
            application/vnd.treasuredata.v1+json:
              schema:
                $ref: '#/components/schemas/EntitiesGetFunnelJsonApiResponse'
    patch:
      tags:
      - Funnels
      summary: Update funnel
      description: Update a funnel.
      parameters:
      - name: id
        in: path
        description: Funnel to update
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/vnd.treasuredata.v1+json:
            schema:
              $ref: '#/components/schemas/EntitiesFunnelUpdateRepresentation'
      responses:
        '200':
          description: Updated funnel
          content:
            application/vnd.treasuredata.v1+json:
              schema:
                $ref: '#/components/schemas/EntitiesGetFunnelJsonApiResponse'
    delete:
      tags:
      - Funnels
      summary: Delete funnel
      description: Delete a funnel.
      parameters:
      - name: id
        in: path
        description: Delete a funnel
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Deleted funnel
          content:
            application/vnd.treasuredata.v1+json:
              schema:
                $ref: '#/components/schemas/EntitiesGetFunnelJsonApiResponse'
  /entities/funnels/{funnelId}/stages/{id}/statistics:
    x-external: true
    get:
      tags:
      - Funnels
      summary: Retrieve population statistics of funnel stage
      description: Retrieve the population history of the audience. The history is returned per day and those days are calculated in the timezone of the audience.
      parameters:
      - name: id
        in: path
        description: Funnel Stage ID to get statistics
        required: true
        schema:
          type: integer
          format: int64
          example: 1234
      - name: funnelId
        in: path
        description: Funnel ID to get statistics
        required: true
        schema:
          type: integer
          format: int64
          example: 1234
      - name: from
        in: query
        description: from date
        schema:
          type: string
          format: date
          example: '2019-01-01'
      - name: to
        in: query
        description: to date (inclusive)
        schema:
          type: string
          format: date
          example: '2019-04-30'
      responses:
        '200':
          description: array of tuple of statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Statistic'
  /entities/parent_segments/{parentSegmentId}/funnels:
    x-external: true
    parameters:
    - $ref: '#/components/parameters/ParentSegmentId'
    get:
      tags:
      - Funnels
      summary: Retrieve list of funnel by parent segment
      description: Retrieve a list of funnels based on a parent segment.
      responses:
        '200':
          description: Returns a list of Funnels.
          content:
            application/vnd.treasuredata.v1+json:
              schema:
                $ref: '#/components/schemas/EntitiesFunnelIndexJsonApiResponse'
components:
  schemas:
    UserJsonApiResource:
      type: object
      required:
      - id
      - type
      - attributes
      properties:
        id:
          type: string
          pattern: '[1-9][0-9]*'
        type:
          type: string
          enum:
          - user
        attributes:
          type: object
          required:
          - tdUserId
          - name
          properties:
            tdUserId:
              type: string
              pattern: '[1-9][0-9]*'
            name:
              type: string
    FunnelStageJsonApiResource:
      type: object
      required:
      - name
      properties:
        id:
          type: string
          pattern: '[1-9][0-9]*'
        segmentId:
          type: string
          pattern: '[1-9][0-9]*'
        name:
          type: string
        numSyndications:
          type: integer
          format: int64
    FunnelJsonApiResource:
      type: object
      required:
      - id
      - type
      - attributes
      - relationships
      properties:
        id:
          type: string
          pattern: '[1-9][0-9]*'
        type:
          type: string
          enum:
          - funnel
        attributes:
          type: object
          required:
          - audienceId
          - name
          - description
          - population
          - numSyndications
          - createdAt
          - updatedAt
          properties:
            audienceId:
              type: string
              pattern: '[1-9][0-9]*'
            name:
              type: string
            description:
              type:
              - string
              - 'null'
            population:
              type:
              - number
              - 'null'
            numSyndications:
              type: integer
              format: int64
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
            countPopulation:
              type: boolean
            stages:
              type: array
              minLength: 3
              maxLength: 8
              items:
                $ref: '#/components/schemas/FunnelStageJsonApiResource'
        relationships:
          type: object
          properties:
            parentFolder:
              $ref: '#/components/schemas/RelationshipsFolderJsonApiResource'
            createdBy:
              $ref: '#/components/schemas/RelationshipsUserJsonApiResource'
            updatedBy:
              $ref: '#/components/schemas/RelationshipsUserJsonApiResource'
    RelationshipsUserJsonApiResource:
      type: object
      properties:
        data:
          type:
          - object
          - 'null'
          required:
          - id
          - type
          properties:
            id:
              type: string
              pattern: '[1-9][0-9]*'
            type:
              type: string
              enum:
              - user
    User:
      type: object
      properties:
        id:
          type: string
          pattern: '[1-9][0-9]*'
        td_user_id:
          type: string
          pattern: '[1-9][0-9]*'
        name:
          type: string
    RelationshipsFolderJsonApiResource:
      type: object
      properties:
        data:
          type: object
          required:
          - id
          - type
          properties:
            id:
              type: string
              pattern: '[1-9][0-9]*'
            type:
              type: string
              enum:
              - folder-segment
    Statistic:
      type: array
      items:
        type: array
        description: a tuple whose values are Unix epoch, the population, whether a workflow has run at that time or not. If the third value is false, it is imputed value.
        example:
        - 1556382847
        - 1234
        - true
        items:
          oneOf:
          - type: integer
            format: int64
          - type: boolean
    Funnel:
      type: object
      properties:
        id:
          type: string
          format: integer
        audienceId:
          type: string
          format: integer
        segmentFolderId:
          type: string
          format: integer
        name:
          type: string
        population:
          type:
          - integer
          - 'null'
          format: int64
          description: The latest population of the funnel
        description:
          type: string
        numSyndications:
          type: integer
          format: int64
        needToRunWorkflow:
          type: boolean
          description: true if need to run workflow to load data
        stages:
          description: funnel stages
          example:
          - id: '1'
            name: Awareness
            numSyndication: 2
            audienceId: '1'
            funnelId: '10'
            segmentFolderId: '30'
            segmentId: '999'
          - id: '2'
            name: Interest
            numSyndications: 0
            audienceId: '1'
            funnelId: '10'
            segmentFolderId: '30'
            segmentId: ''
          - id: '3'
            name: Conversion
            numSyndications: 0
            audienceId: '1'
            funnelId: '10'
            segmentFolderId: '30'
            segmentId: ''
          type: array
          minItems: 3
          maxItems: 8
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              numSyndications:
                type: integer
              audienceId:
                type: string
              funnelId:
                type: string
              segmentFolderId:
                type: string
              segmentId:
                type:
                - string
                - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        createdBy:
          $ref: '#/components/schemas/User'
        updatedBy:
          $ref: '#/components/schemas/User'
    EntitiesFunnelUpdateRepresentation:
      type: object
      properties:
        id:
          type: string
          pattern: '[1-9][0-9]*'
        type:
          type: string
          enum:
          - funnel
        attributes:
          type: object
          properties:
            name:
              type: string
            description:
              type:
              - string
              - 'null'
            stages:
              type: array
              minLength: 3
              maxLength: 8
              items:
                $ref: '#/components/schemas/FunnelStageJsonApiResource'
          required:
          - name
        relationships:
          type: object
          properties:
            parentFolder:
              $ref: '#/components/schemas/RelationshipsFolderJsonApiResource'
          required:
          - parentFolder
    FunnelParameters:
      type: object
      properties:
        name:
          description: name
          type: string
        description:
          description: description
          type: string
        segmentFolderId:
          type: integer
          format: int64
        stages:
          description: funnel stages
          example:
          - name: Awareness
          - id: 1
            name: Interest
          - name: Conversion
          type: array
          minItems: 3
          maxItems: 8
          items:
            type: object
            properties:
              id:
                type: integer
                description: null means new stage, non-null means no-op or updating existing stage name or updating stage orders
              name:
                type: string
            required:
            - name
      required:
      - name
      - segmentFolderId
      - stages
    EntitiesFunnelCreateRepresentation:
      type: object
      properties:
        id:
          type: string
          pattern: '[1-9][0-9]*'
        type:
          type: string
          enum:
          - funnel
        attributes:
          type: object
          properties:
            name:
              type: string
            description:
              type:
              - string
              - 'null'
            stages:
              type: array
              minLength: 3
              maxLength: 8
              items:
                $ref: '#/components/schemas/FunnelStageJsonApiResource'
          required:
          - name
          - stages
        relationships:
          type: object
          properties:
            parentFolder:
              $ref: '#/components/schemas/RelationshipsFolderJsonApiResource'
          required:
          - parentFolder
    FunnelStatistic:
      type: object
      properties:
        population:
          type:
          - integer
          - 'null'
          format: int64
          description: the latest population of the funnel
        stages:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                format: int64
                description: funnel stage id
              history:
                type: array
                items:
                  type: array
                  items:
                    oneOf:
                    - type: integer
                      format: int64
                    - type: boolean
                  description: a tuple whose values are Unix epoch, the population, whether a workflow has run at that time or not
                  example:
                  - 1556382847
                  - 1234
                  - true
      example:
        population: 1000
        stages:
        - id: 44242
          history:
          - - 1600297704
            - 362
            - true
          - - 1600383964
            - 362
            - true
        - id: 44240
          history:
          - - 1600297667
            - 122
            - true
          - - 1600383950
            - 122
            - true
        - id: 44241
          history:
          - - 1600297690
            - 516
            - true
          - - 1600383956
            - 516
            - true
    EntitiesFunnelIndexJsonApiResponse:
      type: object
      required:
      - data
      - included
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FunnelJsonApiResource'
        included:
          type: array
          items:
            $ref: '#/components/schemas/UserJsonApiResource'
    FunnelCloneParameters:
      type: object
      properties:
        name:
          description: name
          type: string
        description:
          description: description
          type: string
        segmentFolderId:
          type: integer
          format: int64
      required:
      - name
      - segmentFolderId
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
      - code
      - message
    EntitiesGetFunnelJsonApiResponse:
      type: object
      required:
      - data
      - included
      properties:
        data:
          $ref: '#/components/schemas/FunnelJsonApiResource'
        included:
          type: array
          items:
            $ref: '#/components/schemas/UserJsonApiResource'
  responses:
    ServerError:
      description: System error. Because there is a possibility of a temporary error due to network trouble and so on, we recommend several times retry on request side. Please contact the TD support team if you do not resolve it.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                format: int64
                description: Error status
              error:
                type: string
                description: Error message
              details:
                type: string
                description: Detailed error message
            required:
            - status
            - error
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ClientError:
      description: There is a high possibility of error of the authentication system. Please check the contents and authority of the key. Please contact the TD support team if you do not resolve it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Given parameters are not valid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Requested resource or action is not allowed because you don't have sufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized; You don't provide valid credentials. Maybe you didn't specify valid TD's Master API Key as 'TD1 {Your TD Master API Key}'.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ParentSegmentId:
      name: parentSegmentId
      in: path
      description: Parent Segment ID (audience id)
      required: true
      schema:
        type: integer
        format: int64
  securitySchemes:
    TdApikeyAuth:
      type: apiKey
      in: header
      name: Authorization
externalDocs:
  description: Treasure Data Support Site
  url: https://support.treasuredata.com/hc/en-us