Ashby Candidate API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Candidate API
  description: The public API for accessing resources in your Ashby instance.
  contact:
    name: Ashby Support
    url: https://app.ashbyhq.com/support
    email: support@ashbyhq.com
servers:
- url: https://api.ashbyhq.com
security:
- BasicAuth: []
tags:
- name: Candidate
paths:
  /candidate.addEmailMessage:
    post:
      summary: candidate.addEmailMessage
      description: 'Adds an email message to a candidate''s profile.


        **Requires the [`candidatesWrite`](authentication#permissions-candidateaddemailmessage) permission.**

        '
      operationId: candidateAddEmailMessage
      tags:
      - Candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - candidateId
              - emailProviderEmailId
              - subject
              - from
              - to
              - body
              properties:
                candidateId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The candidate to attach this email to.
                emailProviderEmailId:
                  type: string
                  description: Unique identifier for this message in the partner system. Must be unique per API key.
                subject:
                  type: string
                  description: The email subject line.
                from:
                  type: string
                  description: The sender email address.
                to:
                  type: string
                  description: The recipient email address.
                body:
                  type: string
                  description: The html body of the email.
                userId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The Ashby user ID to associate with this email. Defaults to the API key user.
                sentAt:
                  allOf:
                  - type: string
                    format: date-time
                    example: '2022-07-21T17:32:28Z'
                  - description: When the email was sent. Defaults to the current time.
                cc:
                  type: string
                  description: CC recipients.
                messageUrl:
                  type: string
                  format: uri
                  description: URL to view the message in the partner application.
                  example: https://example.com/messages/1234567890
                messageIdHeader:
                  type: string
                  description: RFC 5322 message identifier.
                  example: <CADkMx=Abc123@examplemail.com>
                threadId:
                  type: string
                  description: Thread identifier to group this message with others. Defaults to emailProviderEmailId.
                isPrivate:
                  type: boolean
                  description: Whether the email should be marked as private. Private emails require "Allow access to non-offer private fields?" API key permission to create and view. Defaults to false.
                  default: false
      responses:
        '200':
          description: Responses for the candidate.addEmailMessage endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        type: object
                        description: An email sent to or from a candidate.
                        properties:
                          id:
                            $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                            description: The unique id of the email in Ashby.
                          candidateId:
                            $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                            description: The candidate this email is attached to.
                          emailProviderEmailId:
                            type: string
                            description: The unique identifier for this message in the partner system.
                          subject:
                            type: string
                            description: The email subject line.
                          from:
                            type: string
                            description: The sender email address.
                          to:
                            type: string
                            description: The recipient email address.
                          body:
                            type:
                            - string
                            - 'null'
                            description: The body of the email. Can be HTML or plain text.
                          sentAt:
                            $ref: '#/paths/~1candidate.addEmailMessage/post/requestBody/content/application~1json/schema/properties/sentAt/allOf/0'
                            description: When the email was sent.
                          cc:
                            type:
                            - string
                            - 'null'
                            description: CC recipients.
                          messageUrl:
                            type:
                            - string
                            - 'null'
                            format: uri
                            description: URL to view the message in the partner application.
                          messageIdHeader:
                            type:
                            - string
                            - 'null'
                            description: RFC 5322 Message-ID header value.
                          threadId:
                            type: string
                            description: Thread identifier grouping this message with others.
                          isPrivate:
                            type: boolean
                            description: Whether the email is marked as private.
                          userIsSender:
                            type: boolean
                            description: Whether the associated user is the sender (true) or recipient (false).
                        required:
                        - id
                        - candidateId
                        - emailProviderEmailId
                        - subject
                        - from
                        - to
                        - sentAt
                        - isPrivate
                        - userIsSender
                        - threadId
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /candidate.addProject:
    post:
      summary: candidate.addProject
      operationId: candidateaddproject
      description: 'Adds the candidate to a project.


        **Requires the [`candidatesWrite`](authentication#permissions-candidateaddproject) permission.**

        '
      tags:
      - Candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                candidateId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the candidate
                projectId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the project
              required:
              - candidateId
              - projectId
              example:
                candidateId: f9e52a51-a075-4116-a7b8-484deba69004
                projectId: bcffca12-5b09-4a76-acf2-00a8e267b222
      responses:
        '200':
          description: Responses from the candidate.addProject endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1candidate.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /candidate.addTag:
    post:
      summary: candidate.addTag
      description: 'Adds a tag to a candidate


        **Requires the [`candidatesWrite`](authentication#permissions-candidateaddtag) permission.**

        '
      operationId: candidateAddTag
      tags:
      - Candidate
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - candidateId
              - tagId
              properties:
                candidateId:
                  type: string
                  description: The unique id of the candidate to add the tag to.
                  example: 5b591aed-88e3-4395-b9c6-7d529f93354a
                tagId:
                  type: string
                  description: The unique id of the tag to add to the candidate.
                  example: 38430ede-5bd2-41fc-b474-87591cb98cbc
      responses:
        '200':
          description: Responses for the candidate.addTag endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1candidate.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /candidate.anonymize:
    post:
      summary: candidate.anonymize
      description: 'Anonymizes a candidate.


        **Requires the [`candidatesWrite`](authentication#permissions-candidateanonymize) permission.**


        **Note**: this action cannot be reversed and requires all of a candidate''s applications to be in the archived or hired state.

        '
      operationId: candidateAnonymize
      tags:
      - Candidate
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - candidateId
              properties:
                candidateId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the candidate to anonymize.
      responses:
        '200':
          description: Responses for the candidate.anonymize endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    description: The anonymized candidate
                    properties:
                      results:
                        $ref: '#/paths/~1candidate.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /candidate.create:
    post:
      summary: candidate.create
      operationId: candidateCreate
      description: 'Creates a new candidate


        **Requires the [`candidatesWrite`](authentication#permissions-candidatecreate) permission.**


        To set values for custom fields on Candidates, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.

        '
      tags:
      - Candidate
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Adam Hart
                  description: The first and last name of the candidate to be created.
                email:
                  allOf:
                  - type: string
                    example: test@ashbyhq.com
                  - description: Primary, personal email of the candidate to be created.
                phoneNumber:
                  allOf:
                  - type: string
                    example: 555-555-5555
                  - description: Primary, personal phone number of the candidate to be created.
                linkedInUrl:
                  type: string
                  example: https://linkedin.com/in/user
                  description: Url to the candidate's LinkedIn profile. Must be a valid Url.
                githubUrl:
                  type: string
                  example: https://github.com/user
                  description: Url to the candidate's Github profile. Must be a valid Url.
                website:
                  type: string
                  example: https://twitter.com/user
                  description: Url of the candidate's website. Must be a valid Url.
                alternateEmailAddresses:
                  type: array
                  items:
                    type: string
                  example:
                  - test.email@ashbyhq.com
                  description: Array of alternate email address to add to the candidate's profile.
                sourceId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The source to set on the candidate being created.
                creditedToUserId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the user the candidate will be credited to.
                location:
                  type: object
                  description: The location of the candidate.
                  properties:
                    city:
                      type: string
                      example: San Francisco
                      description: The city of the candidate's location.
                    region:
                      type: string
                      example: California
                      description: The region (state, province, etc.) of the candidate's location.
                    country:
                      type: string
                      example: United States
                      description: The country of the candidate's location.
                createdAt:
                  allOf:
                  - description: 'An ISO date string to set the candidate''s `createdAt` timestamp. When this value isn''t provided, the `createdAt` timestamp defaults to the time the call was made.

                      '
                  - $ref: '#/paths/~1candidate.createNote/post/requestBody/content/application~1json/schema/properties/createdAt'
              required:
              - name
      responses:
        '200':
          description: Responses for the candidate.create endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1candidate.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /candidate.createNote:
    post:
      summary: candidate.createNote
      description: "Creates a note on a candidate.\n\n**Requires the [`candidatesWrite`](authentication#permissions-candidatecreatenote) permission.**\n\nFor notes submitted with a type of `text/html`, we support the elements listed below. Any unsupported elements will be stripped out of the note's content before posting.\n  - Bold `<b>`\n  - Italic `<i>`\n  - Underline `<u>`\n  - Links `<a>`\n  - Bulleted Lists - `<ul>`, `<li>`\n  - Ordered Lists - `<ol>`, `<li>`\n  - Code - `<code>`\n  - Code Block - `<pre>`\n"
      operationId: candidateCreateNote
      tags:
      - Candidate
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                candidateId:
                  $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                note:
                  oneOf:
                  - type: string
                    description: The note to add to the candidate
                    example: Strong candidate, very interested in the company
                  - type: object
                    description: Note content
                    properties:
                      type:
                        type: string
                        enum:
                        - text/plain
                        - text/html
                        description: 'The content type of the note. For notes submitted with a type of text/html we support the elements listed below. Any unsupported elements will be stripped out of the note''s content before posting.

                          - Bold `<b>`

                          - Italic `<i>`

                          - Underline `<u>`

                          - Links `<a>`

                          - Bulleted Lists - `<ul>`, `<li>`

                          - Ordered Lists - `<ol>`, `<li>`

                          - Code - `<code>`

                          - Code Block - `<pre>`

                          '
                      value:
                        type: string
                    required:
                    - type
                    - value
                sendNotifications:
                  type: boolean
                  description: Whether or not users who are subscribed to the candidate should be notified that the note was posted. Default is false.
                  default: false
                isPrivate:
                  type: boolean
                  description: Whether the note should be marked as private. Private notes require "Allow access to non-offer private fields?" API key permission to create and view. Default is false.
                  default: false
                createdAt:
                  type: string
                  example: '2022-08-12T20:29:56.964Z'
                  format: date-time
              required:
              - candidateId
              - note
      responses:
        '200':
          description: Responses for the candidate.createNote endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        type: object
                        properties:
                          id:
                            $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          createdAt:
                            $ref: '#/paths/~1candidate.createNote/post/requestBody/content/application~1json/schema/properties/createdAt'
                          isPrivate:
                            type: boolean
                            description: Whether the note is private. Private notes require "Allow access to non-offer private fields?" API key permission to create and view.
                            example: false
                          content:
                            type: string
                            example: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
                          author:
                            type: object
                            properties:
                              id:
                                $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                              firstName:
                                type: string
                                example: Joey
                              lastName:
                                type: string
                                example: Joe
                              email:
                                $ref: '#/paths/~1candidate.create/post/requestBody/content/application~1json/schema/properties/email/allOf/0'
                            required:
                            - id
                            - firstName
                            - lastName
                        required:
                        - id
                        - createdAt
                        - isPrivate
                        - author
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /candidate.info:
    post:
      summary: candidate.info
      operationId: candidateInfo
      description: 'Gets a single candidate by id.


        **Requires the [`candidatesRead`](authentication#permissions-candidateinfo) permission.**

        '
      tags:
      - Candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The id of the candidate to fetch
                required:
                - id
                example:
                  id: f9e52a51-a075-4116-a7b8-484deba69004
              - type: object
                properties:
                  externalMappingId:
                    type: string
                    description: "An id assigned to a candidate outside of Ashby. \nUsed to associate Ashby candidates with their profiles in external systems (BambooHR, Rippling, Gusto, etc.)\n"
                required:
                - externalMappingId
                example:
                  externalMappingId: f9e52a51-a075-4116-a7b8-484deba69004
      responses:
        '200':
          description: Responses from the candidate.info endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        type: object
                        properties:
                          id:
                            $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                            description: The unique id of the candidate
                          createdAt:
                            $ref: '#/paths/~1candidate.createNote/post/requestBody/content/application~1json/schema/properties/createdAt'
                          updatedAt:
                            $ref: '#/paths/~1candidate.createNote/post/requestBody/content/application~1json/schema/properties/createdAt'
                          name:
                            type: string
                            example: Adam Hart
                            description: The candidate's name
                          primaryEmailAddress:
                            $ref: '#/webhooks/pushToHRIS/post/requestBody/content/application~1json/schema/properties/data/properties/application/properties/candidate/properties/primaryEmailAddress'
                          emailAddresses:
                            type: array
                            items:
                              $ref: '#/webhooks/pushToHRIS/post/requestBody/content/application~1json/schema/properties/data/properties/application/properties/candidate/properties/primaryEmailAddress'
                          primaryPhoneNumber:
                            $ref: '#/webhooks/pushToHRIS/post/requestBody/content/application~1json/schema/properties/data/properties/application/properties/candidate/properties/primaryEmailAddress'
                          phoneNumbers:
                            type: array
                            items:
                              $ref: '#/webhooks/pushToHRIS/post/requestBody/content/application~1json/schema/properties/data/properties/application/properties/candidate/properties/primaryEmailAddress'
                          socialLinks:
                            type: array
                            items:
                              $ref: '#/paths/~1candidate.update/post/requestBody/content/application~1json/schema/properties/socialLinks/items'
                          tags:
                            type: array
                            items:
                              $ref: '#/paths/~1candidateTag.create/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                          position:
                            type: string
                            example: Software Engineer
                          company:
                            type: string
                            example: Auction.com
                          school:
                            type: string
                            example: Princeton University
                          applicationIds:
                            type: array
                            description: The unique ids of all applications associated with the candidate
                            items:
                              $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          resumeFileHandle:
                            description: The id, name and handle for the candidate's resume
                            $ref: '#/paths/~1candidate.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/fileHandles/items'
                          fileHandles:
                            description: The id, name and handle for each file associated with the candidate
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                handle:
                                  type: string
                                  description: You can use the file handle to retrieve the file's URL by using the file.info endpoint.
                              required:
                              - id
                              - name
                              - handle
                              example:
                                id: 15d2624d-0a81-4f94-a2ed-94980f430b3f
                                name: resume.pdf
                                handle: eyJoYW5kbGUiOnsidHlwZSI6IkNhbmRpZGF0ZUZpbGUiLCJm
                          customFields:
                            type: array
                            description: All custom field values associated with the candidate
                            items:
                              $ref: '#/paths/~1customField.setValue/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                          profileUrl:
                            type: string
                            description: The url of the candidate's profile in Ashby
                          source:
                            description: The source that created this candidate
                            $ref: '#/paths/~1source.list/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/items'
                          creditedToUser:
                            description: The user who receives credit for this candidate
                            $ref: '#/paths/~1user.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                          timezone:
                            description: The timezone of the candidate
                            type: string
                          location:
                            description: The primary location of the candidate
                            type: object
                            properties:
                              id:
                                $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                                description: The location's unique id.
                              locationSummary:
                                type: string
                                description: A human-readable summary of the location.
                                example: United States, California, San Francisco
                              locationComponents:
                                type: array
                                description: The individual components of the location.
                                items:
                                  type: object
                                  required:
                                  - type
                                  - name
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                      - Country
                                      - Region
                                      - City
                                      description: The type of the location component.
                                    name:
                                      type: string
                                      description: The name of the location component.
                                example:
                                - type: Country
                                  name: United States
                                - type: Region
                                  name: California
                                - type: City
                                  name: San Francisco
                            required:
                            - id
                            - locationSummary
                      

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