sendraven-ai Contact Properties API

openapi: 3.2.0
info:
  title: Sendraven Ai Contact Properties API
  version: 1.0.0
  description: 'Operations tagged Contact Properties 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: Contact Properties
paths:
  /v1/contact-properties:
    get:
      summary: List contact properties
      description: 'Every declared custom field, sorted by name, all of them: the list envelope with has_more always false and next_cursor always null. Check a property''s type before filtering a segment on it with gt or lt.'
      x-required-scope: contacts:read
      responses:
        '200':
          description: Properties
          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/ContactProperty'
                  has_more:
                    type: boolean
                    description: 'Not paged: true only when the list hit its cap, meaning there is more than this endpoint can return.'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                    description: Always null; this list is not paged.
        '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 contacts:read scope. The message names it.'
          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:
      - Contact Properties
      operationId: getV1ContactProperties
      x-operation-id-source: derived
    post:
      summary: Create or update a contact property
      description: 'Declares a property keyed on key: 201 when new, 200 when the key existed (its name is replaced, and its type when sent). Safe to repeat. Leaving type out keeps an existing property''s type, or uses string for a new one. Declare number and boolean properties before importing, so values are stored typed; changing a type later does not convert stored values. Keys are case-sensitive.'
      x-required-scope: contacts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - name
              properties:
                key:
                  type: string
                  pattern: ^[a-zA-Z0-9_]+$
                  description: Letters, digits and underscores only.
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                  description: Display name.
                type:
                  type: string
                  enum:
                  - string
                  - number
                  - boolean
                  - date
                  description: How values are coerced. Defaults to string on create; unchanged on update when left out.
      responses:
        '200':
          description: The key already existed; the updated property
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactProperty'
        '201':
          description: The new property
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactProperty'
        '400':
          description: 'invalid_json: the request body is not valid JSON.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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 contacts:write scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'conflict: another request declared the same key at the same moment. The property exists now; retrying updates it. Also idempotency_in_progress: a request with the same Idempotency-Key was still running on this path after waiting up to 8 seconds for it (a retry that finds it finished receives its response instead). Retry after a short wait.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'payload_too_large: the body is larger than this endpoint accepts (5 MB unless stated).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'invalid_request: key missing or not letters, digits and underscores; name missing, empty or over 120 characters; or type not one of the four ("Validation failed", with details). Also idempotency_key_reused: this Idempotency-Key was already used on this path with a different request body (checked right after the scope, so a credential without the scope gets 403 instead, and answered at once even while the first request is still running). Do not retry; send the new request under a new key.'
          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'
      parameters:
      - name: Idempotency-Key
        in: header
        schema:
          type: string
        description: 'Replaying the same key on the same path in this workspace within 24 hours returns the stored response, with an Idempotent-Replay: true header, instead of acting again. Only successful responses are stored, so a failed request can be fixed and retried under the same key. The body is compared (key order ignored): the same key with a different body is 422 idempotency_key_reused, so use a new key for every new request. Use an unguessable value such as a UUID.'
      tags:
      - Contact Properties
      operationId: postV1ContactProperties
      x-operation-id-source: derived
    servers:
    - url: https://api.sendraven.ai
  /v1/contact-properties/{key}:
    delete:
      summary: Delete a contact property
      description: Removes the definition only. Values stay in every contact's attributes and segment filters on the key keep working; new values are no longer coerced, and an import carrying the key recreates it as string. A key no property has is 404 not_found.
      x-required-scope: contacts:write
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
        description: The property's key, matched exactly (case-sensitive).
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                required:
                - key
                - deleted
                - values_kept
                properties:
                  key:
                    type: string
                  deleted:
                    type: boolean
                    enum:
                    - true
                  values_kept:
                    type: boolean
                    enum:
                    - true
        '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 contacts:write scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: no contact property with this key in the workspace; the message names the key. Nothing was changed.'
          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:
      - Contact Properties
      operationId: deleteV1ContactPropertiesByKey
      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.'
    ContactProperty:
      type: object
      description: A declared custom field. Addressed by key; nothing in the API takes the id.
      required:
      - id
      - key
      - name
      - type
      - created_at
      properties:
        id:
          type: string
          format: uuid
        key:
          type: string
          description: The key in a contact's attributes and in segment filters. Case-sensitive.
        name:
          type: string
        type:
          type:
          - string
          - 'null'
          enum:
          - string
          - number
          - boolean
          - date
          - null
          description: 'How written values are coerced. number: numeric strings convert, true/false/"yes"/"no" become 1/0, anything else 0. boolean: true, 1, "true", "1", "yes" become true, anything else false. string and date: stored as a string (a date is not parsed; send ISO 8601 so gt/lt order it). null only on a property an earlier version of the API cleared; values are then stored as strings. Changing the type does not convert stored values.'
        created_at:
          type: string
          format: date-time
  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