Outreach Prospect API

openapi: 3.2.0
info:
  description: "Outreach Public API is documented here, at the Development Portal, expand the link [Outreach REST API Reference](https://developers.outreach.io/api/reference/overview/) in the left navigation bar to see human-readable description of endpoints and data types.\n\nHowever, if you would like to get machine-readable schema definition there are two other options available:\n\n* [https://api.outreach.io/api/v2/schema.json](https://api.outreach.io/api/v2/schema.json) contains the API definition in  the [json-schema format](https://json-schema.org/) and if you provide `Authorization` header with valid token (same as actual API call) all the custom objects defined for the organization will be included as well.\n\n* [https://api.outreach.io/api/v2/schema/openapi.json](https://api.outreach.io/api/v2/schema/openapi.json) contains the API definition in the [OpenAPI / Swagger format](https://swagger.io/specification/). Unfortunately custom objects are not included in this file.\n\nAdditionally to these standard definitions Outreach provides detailed list of validations applied to custom fields. Custom objects will be included later, the work is in progress.\n\n* [https://api.outreach.io/api/v2/types](https://api.outreach.io/api/v2/types) endpoint returns a list of all `customXXX` fields on standard objects with their type, label, options or other constraints defined by the administrator. This endpoint requires valid token in the `Authorization` header. The format of the definitions is described below.\n\n### Custom field types\n\n```json\n{\n  \"data\": [\n    {\n      \"type\": \"<object_name>\",\n      \"meta\": {\n        \"validations\": {\n          \"<field_name>\": {\n            \"type\": \"<validation_type>\",\n            \"required\": true / false,\n            \"label\": \"...\",\n            \"definition\": null / [\"...\", ...] / \"...\"\n          },\n          ...\n          }\n        }\n      }\n    },\n    ...\n  ]\n}\n```\n\n#### Objects with custom fields\n\n* Account\n* Opportunity\n* OpportunityLineItem\n* OpportunityProspectRole\n* Product\n* Prospect\n* Purchase\n\n#### Validation types\n\n* `boolean` - true or false\n* `currency` - monetary value, `definition` contains an abbreviation of the currency like `\"USD\"` or `\"EUR\"`\n* `date` - a date stored in ISO8601 format: YYYY-MM-DD.\n* `date_time` a date and time stored as YYYY-MM-DDThh:mm:ss.\n* `inclusion` - a pick list with predefined set of options available in `definition` attribute as a list of strings\n* multi_inclusion - a pick list with several options selectable at once with predefined set of options available in `definition` attribute as a list of strings\n* `numerical`\n* `percentage`\n* `phone_number`\n* `string`\n* `url`\n"
  title: Outreach REST API Reference Prospect API
  version: ''
servers:
- url: https://api.outreach.io/api/v2
security:
- bearerAuth: []
tags:
- description: '<SchemaDefinition schemaRef="#/components/schemas/prospect" />


    ## Prospect Relationships


    <SchemaDefinition schemaRef="#/components/schemas/prospectRelationships" />


    ## Prospect Resource Metadata


    | **METADATA NAME**| **DESCRIPTION** | **QUERY PARAM** |

    | --- | --- | --- |

    |  canWrite | A boolean value indicating whether the current API user has write access to this resource. | provideAuthorizationMeta |

    |  canDelete | A boolean value indicating whether the current API user has delete access to this resource. | provideAuthorizationMeta |

    |  dataConnections | The set of connections a given Prospect has to external sources. | provideDataConnections |



    ## ⌵ Prospect Actions


    '
  name: Prospect
  x-internal: false
paths:
  /prospects:
    get:
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/prospectResponse'
                    type: array
          description: OK
        '422':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  errors:
                    items:
                      properties:
                        detail:
                          type: string
                        id:
                          type: string
                        title:
                          type: string
                      type: object
                    type: array
          description: JSON error message
      security:
      - bearerAuth: []
        s2sAuthToken: []
      summary: Get a Collection of Prospects
      tags:
      - Prospect
      x-internal: false
    post:
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              properties:
                data:
                  properties:
                    attributes:
                      $ref: '#/components/schemas/prospect'
                    relationships:
                      $ref: '#/components/schemas/prospectRelationships'
                    type:
                      type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/prospectResponse'
          description: Created
        '422':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  errors:
                    items:
                      properties:
                        detail:
                          type: string
                        id:
                          type: string
                        title:
                          type: string
                      type: object
                    type: array
          description: JSON error message
      security:
      - bearerAuth: []
        s2sAuthToken: []
      summary: Create a New Prospect
      tags:
      - Prospect
      x-internal: false
  /prospects/{id}:
    delete:
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          content:
            application/vnd.api+json: {}
          description: Deleted
        '422':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  errors:
                    items:
                      properties:
                        detail:
                          type: string
                        id:
                          type: string
                        title:
                          type: string
                      type: object
                    type: array
          description: JSON error message
      security:
      - bearerAuth: []
        s2sAuthToken: []
      summary: Delete an Existing Prospect by ID
      tags:
      - Prospect
      x-internal: false
    get:
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/prospectResponse'
          description: OK
        '404':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  errors:
                    items:
                      properties:
                        detail:
                          type: string
                        id:
                          type: string
                        title:
                          type: string
                      type: object
                    type: array
          description: Not Found
      security:
      - bearerAuth: []
        s2sAuthToken: []
      summary: Get a Prospect by ID
      tags:
      - Prospect
      x-internal: false
    patch:
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              properties:
                data:
                  properties:
                    attributes:
                      $ref: '#/components/schemas/prospect'
                    id:
                      type: integer
                    relationships:
                      $ref: '#/components/schemas/prospectRelationships'
                    type:
                      type: string
                  required:
                  - type
                  - id
              type: object
        required: true
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  data:
                    properties:
                      attributes:
                        $ref: '#/components/schemas/prospect'
                      id:
                        type: integer
                      relationships:
                        $ref: '#/components/schemas/prospectRelationships'
                      type:
                        type: string
                    required:
                    - type
                    - id
                type: object
          description: OK
        '422':
          content:
            application/vnd.api+json:
              schema:
                properties:
                  errors:
                    items:
                      properties:
                        detail:
                          type: string
                        id:
                          type: string
                        title:
                          type: string
                      type: object
                    type: array
          description: JSON error message
      security:
      - bearerAuth: []
        s2sAuthToken: []
      summary: Update a Prospect
      tags:
      - Prospect
      x-internal: false
components:
  schemas:
    prospectResponse:
      properties:
        attributes:
          $ref: '#/components/schemas/prospect'
        id:
          type: integer
        relationships:
          $ref: '#/components/schemas/prospectRelationships'
        type:
          type: string
      type: object
      x-internal: false
    prospectRelationships:
      properties:
        account:
          description: The prospect's associated account. You can use attributes id, customId, name, named and updatedAt to filter prospects by account (e.g. filter[account][id]=X). You can force a null return on unnamed account by adding in the request actionParams[withUnnamedAccount]=false.
          properties:
            data:
              properties:
                id:
                  type: integer
                type:
                  enum:
                  - account
                  type: string
              type:
              - object
              - 'null'
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        activeSequenceStates:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The non-finished sequence states where this prospect is the primary recipient. This includes states of "active", "paused", "failed", "bounced", "pending" and "disabled." You can use attributes id and state to filter prospects by activeSequenceStates (e.g. filter[activeSequenceStates][id]=X).'
          properties:
            data:
              items:
                properties:
                  id:
                    type: integer
                  type:
                    enum:
                    - sequenceState
                    type: string
                type: object
              type: array
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        assignedTeams:
          description: ''
          properties:
            data:
              items:
                properties:
                  id:
                    type: integer
                  type:
                    enum:
                    - team
                    type: string
                type: object
              type: array
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        assignedUsers:
          description: ''
          properties:
            data:
              items:
                properties:
                  id:
                    type: integer
                  type:
                    enum:
                    - user
                    type: string
                type: object
              type: array
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        batches:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The batches associated with the prospect.'
          properties:
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        calls:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The calls associated with the prospect. Relationship calls cannot be used as a filter.'
          properties:
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        creator:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The creater of the prospect. Relationship creator cannot be used as a filter.'
          properties:
            data:
              properties:
                id:
                  type: integer
                type:
                  enum:
                  - user
                  type: string
              type:
              - object
              - 'null'
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        defaultPluginMapping:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The default plugin mapping associated with the prospect. If no plugin mapping is enabled, it will return the first plugin mapping associated with the prospect.'
          properties:
            data:
              properties:
                id:
                  type: integer
                type:
                  enum:
                  - pluginMapping
                  type: string
              type:
              - object
              - 'null'
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        emailAddresses:
          description: The prospect's email addresses. Relationship emailAddresses cannot be used as a filter.
          properties:
            data:
              items:
                properties:
                  id:
                    type: integer
                  type:
                    enum:
                    - emailAddress
                    type: string
                type: object
              type: array
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        favorites:
          description: The prospect's favorites. Relationship favorites cannot be used as a filter.
          properties:
            data:
              items:
                properties:
                  id:
                    type: integer
                  type:
                    enum:
                    - favorite
                    type: string
                type: object
              type: array
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        mailings:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The mailings associated with the prospect. Relationship mailings cannot be used as a filter.'
          properties:
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        opportunities:
          description: The opportunities associated with the prospect. Requires the Opportunities SKU to be enabled in order to have access. Please contact support@outreach.io for more assistance. You can use only the attribute id to filter prospects by opportunities (e.g. filter[opportunities][id]=X).
          properties:
            data:
              items:
                properties:
                  id:
                    type: integer
                  type:
                    enum:
                    - opportunity
                    type: string
                type: object
              type: array
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        opportunityProspectRoles:
          description: The roles that associate the prospect with opportunities. Relationship opportunityProspectRoles cannot be used as a filter.
          properties:
            data:
              items:
                properties:
                  id:
                    type: integer
                  type:
                    enum:
                    - opportunityProspectRole
                    type: string
                type: object
              type: array
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        owner:
          description: The owner of the prospect. You can use only the attribute id to filter prospects by owner (e.g. filter[owner][id]=X).
          properties:
            data:
              properties:
                id:
                  type: integer
                type:
                  enum:
                  - user
                  type: string
              type:
              - object
              - 'null'
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        persona:
          description: The persona of the prospect, if it has one. You can use only the attribute id to filter prospects by persona (e.g. filter[persona][id]=X).
          properties:
            data:
              properties:
                id:
                  type: integer
                type:
                  enum:
                  - persona
                  type: string
              type:
              - object
              - 'null'
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        phoneNumbers:
          description: The prospect's phone numbers Relationship phoneNumbers cannot be used as a filter.
          properties:
            data:
              items:
                properties:
                  id:
                    type: integer
                  type:
                    enum:
                    - phoneNumber
                    type: string
                type: object
              type: array
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        sequenceStates:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The sequence states where this prospect is the primary recipient. You can use attributes id and state to filter prospects by sequenceStates (e.g. filter[sequenceStates][id]=X).'
          properties:
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        stage:
          description: The stage the prospect is in. You can use attributes id and name to filter prospects by stage (e.g. filter[stage][id]=X).
          properties:
            data:
              properties:
                id:
                  type: integer
                type:
                  enum:
                  - stage
                  type: string
              type:
              - object
              - 'null'
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        tasks:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The tasks associated with the prospect. Relationship tasks cannot be used as a filter.'
          properties:
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        trashedByAccount:
          description: The account that soft deleted this prospect.
          properties:
            data:
              properties:
                id:
                  type: integer
                type:
                  enum:
                  - account
                  type: string
              type:
              - object
              - 'null'
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
        updater:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The most recent updater of the prospect. Relationship updater cannot be used as a filter.'
          properties:
            data:
              properties:
                id:
                  type: integer
                type:
                  enum:
                  - user
                  type: string
              type:
              - object
              - 'null'
            links:
              properties:
                related:
                  format: uri
                  type: string
              type: object
      type: object
    prospect:
      description: 'A descriptor of a person.

        '
      properties:
        addedAt:
          description: '


            The date and time the prospect was added to any system.'
          format: date-time
          type:
          - string
          - 'null'
          x-internal: false
        addressCity:
          description: '


            The prospect’s city (e.g. "Seattle").'
          maxLength: 255
          type:
          - string
          - 'null'
          x-internal: false
        addressCountry:
          description: '


            The prospect’s country (e.g. "USA").'
          maxLength: 255
          type:
          - string
          - 'null'
          x-internal: false
        addressState:
          description: '


            The prospect’s state (e.g. "Washington").'
          maxLength: 255
          type:
          - string
          - 'null'
          x-internal: false
        addressStreet:
          description: '


            The prospect’s street address (e.g. "1441 N 34th St").'
          maxLength: 255
          type:
          - string
          - 'null'
          x-internal: false
        addressStreet2:
          description: '


            The prospect’s second street address, if applicable.'
          maxLength: 255
          type:
          - string
          - 'null'
          x-internal: false
        addressZip:
          description: '


            The prospect’s postal code (e.g. "98103").'
          maxLength: 255
          type:
          - string
          - 'null'
          x-internal: false
        angelListUrl:
          description: '


            The prospect’s AngelList URL.'
          maxLength: 255
          type:
          - string
          - 'null'
          x-internal: false
        availableAt:
          description: '


            The date and time the prospect is available to contact again.'
          format: date-time
          type:
          - string
          - 'null'
          x-internal: false
        callOptedOut:
          description: '


            Whether the prospect is opted out of calling, or opted out in general if granular opt-out is not enabled.'
          type:
          - boolean
          - 'null'
          x-internal: false
        callsOptStatus:
          description: '


            A string ("opted_in", "opted_out", "null") that represents whether a prospect has opted into or out of calls.'
          maxLength: 255
          type:
          - string
          - 'null'
          x-internal: false
        callsOptedAt:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The date and time the prospect opted in/out of calls.'
          format: date-time
          type:
          - string
          - 'null'
          x-internal: false
        campaignName:
          description: '


            The name of the campaign the prospect is associated with.'
          maxLength: 255
          type:
          - string
          - 'null'
          x-internal: false
        clickCount:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The number of clicks the prospect has made since the last touch point.'
          type:
          - integer
          - 'null'
          x-internal: false
        company:
          description: '


            The name of the company the prospect works at. If associated with an account, this is the name of the account. (e.g. Acme International).'
          type:
          - string
          - 'null'
          x-internal: false
        contactHistogram:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg>


            The last 12 months of email contact history with the prospect, with the current month being the last element. The format for each month is ''[inboundCount, outboundCount]''. Note: Retrieving this field will slow down the queries. Unless this field is required, it is best to filter it out. See Specify Sparse Fieldsets for examples'
          items:
            format: contact histogram
          type:
          - array
          - 'null'
          x-internal: false
        createdAt:
          description: '<img src=https://developers.outreach.io/badges/readonly.svg> <img src=https://developers.outreach.io/badges/filterable.svg> <img src=https://developers.outreach.io/badges/sortable.svg>


            The date and time the prospect was created.'
          format: date-time
          type:
          - string
          - 'null'
          x-internal: false
        custom1:
          description: '


            The value of the prospect’s first custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom2:
          description: '


            The value of the prospect’s second custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom3:
          description: '


            The value of the prospect’s third custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom4:
          description: '


            The value of the prospect’s fourth custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom5:
          description: '


            The value of the prospect’s fifth custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom6:
          description: '


            The value of the prospect’s sixth custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom7:
          description: '


            The value of the prospect’s seventh custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom8:
          description: '


            The value of the prospect’s eight custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom9:
          description: '


            The value of the prospect’s ninth custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom10:
          description: '


            The value of the prospect’s 10th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom11:
          description: '


            The value of the prospect’s 11th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom12:
          description: '


            The value of the prospect’s 12th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom13:
          description: '


            The value of the prospect’s 13th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom14:
          description: '


            The value of the prospect’s 14th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom15:
          description: '


            The value of the prospect’s 15th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom16:
          description: '


            The value of the prospect’s 16th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom17:
          description: '


            The value of the prospect’s 17th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom18:
          description: '


            The value of the prospect’s 18th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom19:
          description: '


            The value of the prospect’s 19th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom20:
          description: '


            The value of the prospect’s 20th custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom21:
          description: '


            The value of the prospect’s 21st custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom22:
          description: '


            The value of the prospect’s 22nd custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom23:
          description: '


            The value of the prospect’s 23rd custom field.'
          maxLength: 32000
          type:
          - string
          - 'null'
          x-internal: false
        custom24:
          description: '


            The value of the prospect’s 24th custom field.'
          maxLength: 32000
       

# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/outreach/refs/heads/main/openapi/outreach-prospect-api-openapi.yml