sendraven-ai Conversions API

openapi: 3.2.0
info:
  title: Sendraven Ai Conversions API
  version: 1.0.0
  description: 'Operations tagged Conversions across 2 of this provider''s published API definitions: sendraven-ai-api-openapi.json, sendraven-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sendraven.ai
security:
- bearerAuth: []
tags:
- name: Conversions
paths:
  /v1/conversions:
    get:
      summary: List conversions
      description: Every recorded conversion, newest first, with the message it was credited to. Pending ones are included; filter with status=attributed for only the credited.
      x-required-scope: broadcasts:read
      parameters:
      - name: goal_id
        in: query
        schema:
          type: string
          format: uuid
        description: Only this goal's conversions. All goals when left out.
      - name: broadcast_id
        in: query
        schema:
          type: string
          format: uuid
        description: Only conversions credited to this campaign. Not with automation_id.
      - name: automation_id
        in: query
        schema:
          type: string
          format: uuid
        description: Only conversions credited to this automation. Not with broadcast_id.
      - name: from
        in: query
        schema:
          type: string
          format: date-time
        description: Conversions at or after this time (when the event was received).
      - name: to
        in: query
        schema:
          type: string
          format: date-time
        description: Conversions before this time.
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - attributed
          - unattributed
      - name: email
        in: query
        schema:
          type: string
          format: email
        description: One person's conversions.
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Page size. A larger value is capped at 100, a fraction is rounded down, and zero, a negative or a non-number falls back to 50. None of these is an error.
      - name: cursor
        in: query
        schema:
          type: string
        description: The next_cursor from the previous page, passed back unchanged. An unreadable cursor returns the first page.
      responses:
        '200':
          description: A page of conversions.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - data
                - has_more
                - next_cursor
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversion'
                  has_more:
                    type: boolean
                    description: True when another page exists; pass next_cursor back as cursor.
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '401':
          description: 'unauthorized: no Bearer token, or the key or token is invalid, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: the key lacks the broadcasts:read scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: goal_id, broadcast_id or automation_id names nothing in the workspace.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'invalid_request: a filter is malformed, or both broadcast_id and automation_id were given.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'rate_limited: more requests than the per-key rate (600 a minute by default). Wait the seconds in the Retry-After header and retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'service_unavailable: the API is under heavy load and could not get a database connection in time. Usually nothing was done; a send that was already under way may have been, so check GET /v1/emails before retrying one. Wait the seconds in the Retry-After header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Conversions
      operationId: getV1Conversions
      x-operation-id-source: derived
    servers:
    - url: https://api.sendraven.ai
  /v1/conversions/metrics:
    get:
      summary: Conversion metrics
      description: Attributed conversions, distinct converters and revenue per currency. Scoped to one campaign (broadcast_id), it adds the messages sent and the conversion rate, and per variant for an A/B test; scoped to one automation (automation_id), per step. The rate counts people, so one reader buying twice does not double it; revenue counts every purchase. Pending and unattributed conversions are not counted.
      x-required-scope: broadcasts:read
      parameters:
      - name: goal_id
        in: query
        schema:
          type: string
          format: uuid
        description: Only this goal's conversions. All goals when left out.
      - name: broadcast_id
        in: query
        schema:
          type: string
          format: uuid
        description: Only conversions credited to this campaign. Not with automation_id.
      - name: automation_id
        in: query
        schema:
          type: string
          format: uuid
        description: Only conversions credited to this automation. Not with broadcast_id.
      - name: from
        in: query
        schema:
          type: string
          format: date-time
        description: Conversions at or after this time (when the event was received).
      - name: to
        in: query
        schema:
          type: string
          format: date-time
        description: Conversions before this time.
      responses:
        '200':
          description: Metrics for the scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionMetrics'
        '401':
          description: 'unauthorized: no Bearer token, or the key or token is invalid, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: the key lacks the broadcasts:read scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: goal_id, broadcast_id or automation_id names nothing in the workspace.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'invalid_request: a filter is malformed, or both broadcast_id and automation_id were given.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'rate_limited: more requests than the per-key rate (600 a minute by default). Wait the seconds in the Retry-After header and retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'service_unavailable: the API is under heavy load and could not get a database connection in time. Usually nothing was done; a send that was already under way may have been, so check GET /v1/emails before retrying one. Wait the seconds in the Retry-After header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Conversions
      operationId: getV1ConversionsMetrics
      x-operation-id-source: derived
    servers:
    - url: https://api.sendraven.ai
  /v1/conversions/{id}:
    get:
      summary: Retrieve a conversion
      x-required-scope: broadcasts:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The conversion's id, from conversion_id on POST /v1/events or from GET /v1/conversions.
      responses:
        '200':
          description: The conversion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversion'
        '401':
          description: 'unauthorized: no Bearer token, or the key or token is invalid, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: the key lacks the broadcasts:read scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: no conversion with this id in the workspace.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'rate_limited: more requests than the per-key rate (600 a minute by default). Wait the seconds in the Retry-After header and retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'service_unavailable: the API is under heavy load and could not get a database connection in time. Usually nothing was done; a send that was already under way may have been, so check GET /v1/emails before retrying one. Wait the seconds in the Retry-After header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Conversions
      operationId: getV1ConversionsById
      x-operation-id-source: derived
    servers:
    - url: https://api.sendraven.ai
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - message
          properties:
            type:
              type: string
              description: 'Stable and safe to branch on, and the same status on every route: invalid_request (422), invalid_json (400), payload_too_large (413), unauthorized (401), forbidden (403), not_found (404), conflict (409, an identifier already taken), invalid_state (409, the resource''s current state does not allow this), plan_limit_reached (402), payment_method_required (402), billing_past_due (402), budget_exceeded (402), no_verified_identity (422), missing_variables (422), unknown_topic (422), idempotency_in_progress (409), idempotency_key_reused (422), approval_in_progress (409), rate_limited (429), daily_limit (429), recipient_not_allowed (403), invalid_schedule (422), warmup_limit (422), no_postal_address (422), workspace_suspended (422), gone (410), ses_error (502), internal_error (500), service_unavailable (503).'
            message:
              type: string
              description: For people; may change.
            details:
              type: array
              items:
                type: object
                additionalProperties: true
              description: 'On many 422 invalid_request answers: one entry per field that failed validation.'
            missing:
              type: array
              items:
                type: string
              description: 'Only on missing_variables, and always there: the names of the template variables that were not supplied.'
    ConversionMetrics:
      type: object
      required:
      - goal_id
      - broadcast_id
      - automation_id
      - from
      - to
      - conversions
      - converters
      - revenue
      - sent
      - conversion_rate
      - by_variant
      - by_step
      properties:
        goal_id:
          type:
          - string
          - 'null'
          description: The goal_id filter, or null for all goals.
        broadcast_id:
          type:
          - string
          - 'null'
        automation_id:
          type:
          - string
          - 'null'
        from:
          type:
          - string
          - 'null'
          format: date-time
        to:
          type:
          - string
          - 'null'
          format: date-time
        conversions:
          type: integer
          minimum: 0
          description: Attributed conversions, counting every purchase.
        converters:
          type: integer
          minimum: 0
          description: Distinct people among them.
        revenue:
          type: array
          description: Summed value per currency, from conversions that carried one. Values in different currencies are never added together, so a single-currency workspace has one entry and one with no values has none.
          items:
            type: object
            required:
            - currency
            - amount
            properties:
              currency:
                type: string
                description: ISO 4217, upper case.
              amount:
                type: number
                description: Rounded to two decimal places.
        sent:
          type:
          - integer
          - 'null'
          minimum: 0
          description: Messages the campaign or automation sent. null unless broadcast_id or automation_id is given.
        conversion_rate:
          type:
          - number
          - 'null'
          description: converters / sent. null when sent is null or 0.
        by_variant:
          type:
          - array
          - 'null'
          description: One row per A/B variant, in the campaign's order. null unless broadcast_id names an A/B test.
          items:
            type: object
            required:
            - key
            - conversions
            - converters
            - revenue
            - sent
            - conversion_rate
            properties:
              key:
                type: string
              conversions:
                type: integer
                minimum: 0
                description: Attributed conversions, counting every purchase.
              converters:
                type: integer
                minimum: 0
                description: Distinct people among them.
              revenue:
                type: array
                description: Summed value per currency, from conversions that carried one. Values in different currencies are never added together, so a single-currency workspace has one entry and one with no values has none.
                items:
                  type: object
                  required:
                  - currency
                  - amount
                  properties:
                    currency:
                      type: string
                      description: ISO 4217, upper case.
                    amount:
                      type: number
                      description: Rounded to two decimal places.
              sent:
                type: integer
                minimum: 0
                description: Messages accepted for sending in this row.
              conversion_rate:
                type:
                - number
                - 'null'
                description: converters / sent, 0 to 1 in practice. null when sent is 0.
        by_step:
          type:
          - array
          - 'null'
          description: One row per current step, in order. Figures follow the step id, so a step keeps its own conversions after the sequence is edited. null unless automation_id is given.
          items:
            type: object
            required:
            - step
            - step_id
            - conversions
            - converters
            - revenue
            - sent
            - conversion_rate
            properties:
              step:
                type: integer
                minimum: 1
                description: Its position now, numbered from 1.
              step_id:
                type: string
              conversions:
                type: integer
                minimum: 0
                description: Attributed conversions, counting every purchase.
              converters:
                type: integer
                minimum: 0
                description: Distinct people among them.
              revenue:
                type: array
                description: Summed value per currency, from conversions that carried one. Values in different currencies are never added together, so a single-currency workspace has one entry and one with no values has none.
                items:
                  type: object
                  required:
                  - currency
                  - amount
                  properties:
                    currency:
                      type: string
                      description: ISO 4217, upper case.
                    amount:
                      type: number
                      description: Rounded to two decimal places.
              sent:
                type: integer
                minimum: 0
                description: Messages accepted for sending in this row.
              conversion_rate:
                type:
                - number
                - 'null'
                description: converters / sent, 0 to 1 in practice. null when sent is 0.
    Conversion:
      type: object
      required:
      - id
      - goal_id
      - event_name
      - email
      - external_id
      - value
      - currency
      - status
      - occurred_at
      - message_id
      - clicked_at
      - broadcast_id
      - variant
      - automation_id
      - automation_step
      - automation_step_id
      - attributed_at
      properties:
        id:
          type: string
          format: uuid
        goal_id:
          type: string
          format: uuid
        event_name:
          type: string
        email:
          type: string
          description: Lowercased.
        external_id:
          type:
          - string
          - 'null'
          description: The id sent with the event, or null.
        value:
          type:
          - number
          - 'null'
        currency:
          type:
          - string
          - 'null'
          description: ISO 4217, upper case. Present exactly when value is.
        status:
          type: string
          enum:
          - pending
          - attributed
          - unattributed
          description: pending for the first seconds, while the clicks that could earn it are still being checked for security scanners. attributed once credited to the last email the person clicked within the goal's window. unattributed when no click by a person falls in the window. Opens never earn credit.
        occurred_at:
          type: string
          format: date-time
          description: When the event was received.
        message_id:
          type:
          - string
          - 'null'
          description: The credited message. null unless attributed.
        clicked_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the credited click happened.
        broadcast_id:
          type:
          - string
          - 'null'
          description: The campaign the credited message belongs to, if any.
        variant:
          type:
          - string
          - 'null'
          description: Its A/B variant key, if any.
        automation_id:
          type:
          - string
          - 'null'
          description: The automation that sent the credited message, if any.
        automation_step:
          type:
          - integer
          - 'null'
          minimum: 1
          description: Its step's position when the email was sent, numbered from 1.
        automation_step_id:
          type:
          - string
          - 'null'
          description: Its step's id, which stays the same when steps are added, removed or reordered.
        attributed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the status left pending. null while pending.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key of the form sk_live_…, created at /developers, or an OAuth access token (srv_oat_…). An OAuth token carries its grant's scopes but none of an API key's guardrails, and cannot decide approvals.
x-refined-from:
- sendraven-ai-api-openapi.json
- sendraven-ai-openapi.json