LogoLogo
  • Endorsed Platform Overview
  • API Overview
  • Data Import
  • Candidate Querying
  • Support
  • Common Workflows
    • Applicant Tracking Systems
      • Bring AI-powered candidate search to your users
      • Bring lookalike search to your users
      • Bring AI-powered evaluations to your users
    • Recruitment Marketplaces
      • Screen New Marketplace Applicants for Internal Team
      • Find, Score, and Summarize Talent for Client Jobs for Internal Team
      • Talent Search APIs for Your Users
  • Reference
    • API Reference
      • Access Tokens
      • Jobs
      • Spotlights
      • Job Criteria
      • Nomination Stages
      • Candidates
      • Nominations
      • Attachments
      • Rankings
      • Summaries
      • Tags
      • Candidate Tags
      • Job Tags
      • Criterion Evaluations
      • SDK (Coming Soon)
      • Quick Start (Coming Soon)
  • Resources
    • How to Write Good Evaluation Criteria
    • HIRE Accuracy Benchmark
      • HIRE Benchmark: Setting the Standard for Candidate Evaluation AI
Powered by GitBook

© 2024 Endorsed

On this page
  • Create an attachment
  • Get an existing attachment
  • Update or Upsert an attachment
  • Delete an existing attachment
  1. Reference
  2. API Reference

Attachments

An attachment represents a successfully uploaded file that may or may not be associated with an candidate.

Relationships:

  • Candidate to Attachment is 1-Many

Create an attachment

POST https://endorsed.ai/api/v1/attachments

Creates a new attachment through a file upload and returns the attachment's UUID id. Parameters are shown as a Body but are accepted as FormData for Content-Type of multipart/form-data and request body for Content-Type of application/json.

Headers

Name
Type
Description

Authorization*

string

Authorization header containing the Bearer Access Token from the /auth/tokens endpoint. Example: Bearer <ACCESS_TOKEN>

Content-Type

string

Only supports multipart/form-data and application/json. Defaults to multipart/form-data if not set

Request Body

Name
Type
Description

candidate_id

string

The Candidate UUID from the /candidates entity resource. Field can be left optional for the rare case of attachments NOT directly associated with an candidate id; empty should ONLY be used in rare cases such as lookalike search.

remote_id*

string

The

id

of the attachment from the originating system

type*

string

Type of the attachment: Only currently supports about, resume, role_preferences, and work_experiences.

file

file

The file (binary format) to be uploaded. Required if Content-Type header is multipart/form-data; else should not be set.

public_file_url

string

The publicly accessible file url for Endorsed to download the file from. Required if Content-Type header is application/json; else should not be set.

file_name

string

Name of the file

{
  "is_error": false,
  "result": {
    "id": "44e40fec-6144-4c86-b71a-857fb1c2c625"
  }
}
{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}
{
  "is_error": true,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "issues": [
      {
        "message": "An unexpected error occurred on our end. Please try again later, and if the problem persists, contact our support team"
      }
    ]
  }
}

Examples:

curl -X POST "${BASE_URL}/api/v1/attachments" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "remote_id": "remote-id_from-originating-system",
  "type": "resume",
  "public_file_url": "https://file-hosting-domain.com/public-example-file-name.pdf",
  "file_name": "public-example-file-name.pdf",
  "candidate_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}'
curl -X POST "${BASE_URL}/api/v1/attachments" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: multipart/form-data" \
  -F "remote_id=remote-id_from-originating-system" \
  -F "type=resume" \
  -F "file_name=resume-file.pdf" \
  -F "file=@./resume-file.pdf" \
  -F "candidate_id=f47ac10b-58cc-4372-a567-0e02b2c3d479"

Get an existing attachment

GET https://endorsed.ai/api/v1/attachments/{id}

Get an existing attachment by it's UUID id or by a remote id. Remote ids MUST be structured by remote.<id>

Path Parameters

Name
Type
Description

id*

string

UUID id of the Attachment

Headers

Name
Type
Description

Authorization*

string

Authorization header containing the Bearer Access Token from the /auth/tokens endpoint. Example: Bearer <ACCESS_TOKEN>

{
  "is_error": false,
  "result": {
    "id": "44e40fec-6144-4c86-b71a-857fb1c2c625",
    "remote_id": "remote-id_from-originating-system",
    "type": "resume",
    "file_name": "resume-file.pdf",
    "candidate_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "ephemeral_url": "https://endorsed.ai/raw_attachments_url/551924a1-9490-4799-b850-f9e5d4ed4225.pdf",
    "created_at": "2023-09-25T22:06:01.000Z",
    "modified_at": "2023-09-25T22:06:01.000Z"
  }
}
{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}
{
  "is_error": true,
  "error": {
    "code": "FORBIDDEN",
    "issues": [
      {
        "message": "Access to this resource is not authorized."
      }
    ]
  }
}
{
  "is_error": true,
  "error": {
    "code": "NOT_FOUND",
    "issues": [
      {
        "message": "This resource entity does not exist."
      }
    ]
  }
}
{
  "is_error": true,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "issues": [
      {
        "message": "An unexpected error occurred on our end. Please try again later, and if the problem persists, contact our support team"
      }
    ]
  }
}

Examples:

curl -X GET "${BASE_URL}/api/v1/attachments/remote.remote-id_from-originating-system" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
curl -X GET "${BASE_URL}/api/v1/attachments/44e40fec-6144-4c86-b71a-857fb1c2c625" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Update or Upsert an attachment

PUT https://endorsed.ai/api/v1/attachments/{id}

Updates or Upserts a new attachment through a file upload and returns the attachment's UUID id or remote id. Remote ids MUST be structured by remote.<id>.

Parameters are shown as a Body but are accepted as FormData for Content-Type of multipart/form-data and request body for Content-Type of application/json.

Path Parameters

Name
Type
Description

id*

string

UUID id or Remote Id of the Attachment. Remote ids MUST be structured by remote.<id>.

Headers

Name
Type
Description

Authorization*

string

Authorization header containing the Bearer Access Token from the /auth/tokens endpoint. Example: Bearer <ACCESS_TOKEN>

Content-Type

string

Only supports multipart/form-data and application/json. Defaults to multipart/form-data if not set

Request Body

Name
Type
Description

candidate_id

string

The Candidate UUID from the /candidates entity resource. Field can be left optional for the rare case of attachments NOT directly associated with an candidate id; empty should ONLY be used in rare cases such as lookalike search.

remote_id*

string

The

id

of the attachment from the originating system

type*

string

Type of the attachment: Only currently supports about, resume, role_preferences, and work_experiences.

file

file

The file (binary format) to be uploaded. Required if Content-Type header is multipart/form-data; else should not be set.

public_file_url

string

The publicly accessible file url for Endorsed to download the file from. Required if Content-Type header is application/json; else should not be set.

file_name

string

Name of the file

{
  "is_error": false,
  "result": {
    "id": "44e40fec-6144-4c86-b71a-857fb1c2c625"
  }
}
{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}
{
  "is_error": true,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "issues": [
      {
        "message": "An unexpected error occurred on our end. Please try again later, and if the problem persists, contact our support team"
      }
    ]
  }
}

Examples:

curl -X PUT "${BASE_URL}/api/v1/attachments/44e40fec-6144-4c86-b71a-857fb1c2c625" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "remote_id": "remote-id_from-originating-system",
  "type": "resume",
  "public_file_url": "https://file-hosting-domain.com/public-example-file-name.pdf",
  "file_name": "public-example-file-name.pdf",
  "candidate_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}'
curl -X PUT "${BASE_URL}/api/v1/attachments/44e40fec-6144-4c86-b71a-857fb1c2c625" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: multipart/form-data" \
  -F "remote_id=remote-id_from-originating-system" \
  -F "type=resume" \
  -F "file_name=resume-file.pdf" \
  -F "file=@./resume-file.pdf" \
  -F "candidate_id=f47ac10b-58cc-4372-a567-0e02b2c3d479"
curl -X PUT "${BASE_URL}/api/v1/attachments/remote.remote-id_from-originating-system" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "remote_id": "remote-id_from-originating-system",
  "type": "resume",
  "public_file_url": "https://file-hosting-domain.com/public-example-file-name.pdf",
  "file_name": "public-example-file-name.pdf",
  "candidate_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}'
curl -X PUT "${BASE_URL}/api/v1/attachments/remote.remote-id_from-originating-system" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: multipart/form-data" \
  -F "remote_id=remote-id_from-originating-system" \
  -F "type=resume" \
  -F "file_name=resume-file.pdf" \
  -F "file=@./resume-file.pdf" \
  -F "candidate_id=f47ac10b-58cc-4372-a567-0e02b2c3d479"

Delete an existing attachment

DELETE https://endorsed.ai/api/v1/attachments/{id}

Delete an existing attachment (metadata & file) by it's UUID id.

Path Parameters

Name
Type
Description

id*

string

UUID id of the Attachment

Headers

Name
Type
Description

Authorization*

string

Authorization header containing the Bearer Access Token from the /auth/tokens endpoint. Example: Bearer <ACCESS_TOKEN>

{
  "is_error": false,
  "result": {
    "id": "44e40fec-6144-4c86-b71a-857fb1c2c625"
  }
}
{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}
{
  "is_error": true,
  "error": {
    "code": "FORBIDDEN",
    "issues": [
      {
        "message": "Access to this resource is not authorized."
      }
    ]
  }
}
{
  "is_error": true,
  "error": {
    "code": "NOT_FOUND",
    "issues": [
      {
        "message": "This resource entity does not exist."
      }
    ]
  }
}
{
  "is_error": true,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "issues": [
      {
        "message": "An unexpected error occurred on our end. Please try again later, and if the problem persists, contact our support team"
      }
    ]
  }
}

Examples:

curl -X DELETE "${BASE_URL}/api/v1/attachments/44e40fec-6144-4c86-b71a-857fb1c2c625" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Last updated 1 year ago