API Reference

Create Application

post
https://{subdomain}.pinpointhq.com/api/v1/applications
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Request format

In order to create an application you must send a JSON:API spec JSON object representing a job application.

Required attributes

As a bare minimum, first_name, last_name, and email must be supplied. Other required attributes will vary depending on the job configuration.

Job requirementApplication Required fields
Phonephone, phone_iso2
Addressaddress1, town, country, postcode
Résumè / CVcv_base64_filename, cv_base64_data
Personal Summarysummary

Required relationships

Only the job is required when creating an application, although the stage and answers can also be optionally specified.

The application will automatically be assigned to the applied stage of the job if no stage is specified.

Sending Notifications

When an application is created there are two notifications that are sent out:

  • Application Received is sent to the applicant
  • New Application is sent to relevant Pinpoint users

If you want to avoid sending notifications, E.g. if you are importing applicants into Pinpoint as part of a migration, then supply a skip_notifications_on_create attribute with a value of true.

Examples

{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      }
    }
  }
}
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "stage": {
        "data": {
          "type": "stages",
          "id": "1"
        }
      }
    }
  }
}
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]",
      "phone": "02033189441",
      "phone_iso2": "JE",
      "address1": "One Waverley Place",
      "address2": "Union Street",
      "town": "St Helier",
      "country": "Jersey",
      "postcode": "JE1 2PP",
      "date_of_birth": "1970-01-01",
      "linkedin_url": "https://www.linkedin.com/company/pinpointhq",
      "summary": "This is my personal summary",
      "cv_base64_filename": "joe_bloggs_resume.pdf",
      "cv_base64_data": "data:application/pdf;base64,...[DATA]...",
      "equality_monitoring_option_ids": ["1","11"],
      "channel": "event",
      "channel_source": "Spring marketing campaign"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "custom_attributes": {
        "data": [
            {
              "type": "custom_attributes",
              "temp-id": "temp-id-1",
              "method": "create"
            }
        ]
      },
      "answers": {
        "data": [
          {
            "type": "answers",
            "method": "create",
            "temp-id": "1"
          },
          {
            "type": "answers",
            "method": "create",
            "temp-id": "2"
          },
          {
            "type": "answers",
            "method": "create",
            "temp-id": "3"
          },
          {
            "type": "answers",
            "method": "create",
            "temp-id": "4"
          },
          {
            "type": "answers",
            "method": "create",
            "temp-id": "5"
          },
          {
            "type": "answers",
            "method": "create",
            "temp-id": "6"
          },
          {
            "type": "answers",
            "method": "create",
            "temp-id": "7"
          },
          {
            "type": "answers",
            "method": "create",
            "temp-id": "8"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "custom_attributes",
      "temp-id": "temp-id-1",
      "attributes": {
        "varchar_value": "example text value"
      },
      "relationships": {
        "custom_field": {
          "data": {
            "type": "custom_fields",
            "id": "11"
          }
        }
      }
    },
    {
      "type": "answers",
      "temp-id": "1",
      "attributes": {
        "boolean_answer": true
      },
      "relationships": {
        "question": {
          "data": {
            "id": "1",
            "type": "questions"
          }
        }
      }
    },
    {
      "type": "answers",
      "temp-id": "2",
      "attributes": {
        "text_answer": "This is the first line of a multiline answer/nThis is the second line"
      },
      "relationships": {
        "question": {
          "data": {
            "id": "2",
            "type": "questions"
          }
        }
      }
    },
    {
      "type": "answers",
      "temp-id": "3",
      "attributes": {},
      "relationships": {
        "answer_options": {
          "data": [
            {
              "type": "answer_options",
              "method": "create",
              "temp-id": "answer-option-1"
            },
            {
              "type": "answer_options",
              "method": "create",
              "temp-id": "answer-option-2"
            }
          ]
        },
        "question": {
          "data": {
            "id": "3",
            "type": "questions"
          }
        }
      }
    },
    {
      "type": "answers",
      "temp-id": "4",
      "attributes": {
        "document_base64_filename": "some other pdf.pdf",
        "document_base64_data": "data:application/pdf;base64,...[DATA]..."
      },
      "relationships": {
        "question": {
          "data": {
            "id": "4",
            "type": "questions"
          }
        }
      }
    },
    {
      "type": "answers",
      "temp-id": "5",
      "attributes": {
        "date_answer": "2024-06-06"
      },
      "relationships": {
        "question": {
          "data": {
            "id": "5",
            "type": "questions"
          }
        }
      }
    },
    {
      "type": "answers",
      "temp-id": "6",
      "attributes": {
        "url_answer": "https://pinpointhq.com"
      },
      "relationships": {
        "question": {
          "data": {
            "id": "6",
            "type": "questions"
          }
        }
      }
    },
    {
      "type": "answers",
      "temp-id": "7",
      "attributes": {
        "text_answer": "Ruby"
      },
      "relationships": {
        "question": {
          "data": {
            "id": "7",
            "type": "questions"
          }
        }
      }
    },
    {
      "type": "answers",
      "temp-id": "8",
      "attributes": {
        "number_answer": 42
      },
      "relationships": {
        "question": {
          "data": {
            "id": "8",
            "type": "questions"
          }
        }
      }
    },
    {
      "type": "answer_options",
      "temp-id": "answer-option-1",
      "attributes": {
        "text": "Ruby"
      }
    },
    {
      "type": "answer_options",
      "temp-id": "answer-option-2",
      "attributes": {
        "text": "Blue"
      }
    }
  ]
}
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]",
      "skip_notifications_on_create": true
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      }
    }
  }
}

Attaching a résumè / CV

A CV can be supplied with the request by populating both fields shown below. If only one of the fields is present then no CV will be saved.

Field NameDescription
cv_base64_filenameThe name of the file. This is how it will appear within Pinpoint.
cv_base64_dataA Base64 encoded DataURL

Validations

  • Accepted file formats are pdf, doc, and docx.
  • File size limit is 30 megabytes.

Example

{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]",
      "cv_base64_filename": "cv.pdf", 
      "cv_base64_data": "data:application/pdf;base64,...[DATA]..."
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      }
    }
  }
}

Attaching cover letter

A cover letter works in the same way.

Field NameDescription
cover_letter_base64_filenameThe name of the file. This is how it will appear within Pinpoint.
cover_letter_base64_dataA Base64 encoded DataURL

Validations

  • Accepted file formats are pdf, doc, docx, txt, rtf
  • File size limit is 30 megabytes.

Example

{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]",
      "cover_letter_base64_filename": "cover_letter.pdf", 
      "cover_letter_base64_data": "data:application/pdf;base64,...[DATA]..."
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      }
    }
  }
}

Upload documents

You can upload multiple documents (besides CV) using the documents_base64 array on the attributes.

[
  {
    "data": "data:application/pdf;base64,...[DATA]...",
    "filename": "background_check.pdf"
  },
	{
    "data": "data:image/jpeg;base64,...[DATA]...",
    "filename": "scan.jpg"
  }
]

Accepted file types: pdf, doc, docx, png, jpeg, xls, xlsx, pptx, mp4, mov, txt.

Maximum file size: 10 MB per file.

There is currently no way to delete application documents via the API.

Submitting answers along with an application

Applications can be created with additional answers in a single request. These answers will relate to job specific questions, which can be retrieved using the job API endpoints.

A temp-id field is required when detailing the answer under the relationships key of the POST body. This temp-id can be any UUID and will help to:

  • Connect relevant sections of the payload.
  • Associate in-memory objects with the ids returned from the server.
  • Make it easy to associate any errors returned from failed requests.

Required Fields and relationships.

An answers required attributes will depend on the type of the question that it's associated with.

Question typeRequired attributesRequired Relationships
short_text or long_texttext_answerquestion
booleanboolean_answerquestion
numbernumber_answerquestion
urlurl_answerquestion
documentdocument_base64_filename, document_base64_data. This is done in the same way as submitting a CV.question
multiple_choiceNonequestion, answer_options. See the example below for how to submit the answer options.

Required questions

When creating an application through the API, Pinpoint will not validate that answers to required questions are present.

I.e. if you have a job that has a required question, you can still create an application without providing an answer to this question. It is because of this that validations for required answers must be done on the client side.

Examples of how to submit different answer types

{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "answers": {
        "data": [
          {
            "type": "answers",
            "method": "create",
            "temp-id": "1"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "answers",
      "temp-id": "1",
      "attributes": {
        "text_answer": "This is the first line of a multiline answer/nThis is the second line"
      },
      "relationships": {
        "question": {
          "data": {
            "id": "1",
            "type": "questions"
          }
        }
      }
    }
  ]
}
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "answers": {
        "data": [
          {
            "type": "answers",
            "method": "create",
            "temp-id": "1"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "answers",
      "temp-id": "1",
      "attributes": {
        "boolean_answer": true
      },
      "relationships": {
        "question": {
          "data": {
            "id": "1",
            "type": "questions"
          }
        }
      }
    }
  ]
}
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "answers": {
        "data": [
          {
            "type": "answers",
            "method": "create",
            "temp-id": "1"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "answers",
      "temp-id": "1",
      "attributes": {
        "number_answer": 123
      },
      "relationships": {
        "question": {
          "data": {
            "id": "2",
            "type": "questions"
          }
        }
      }
    }
  ]
}
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "answers": {
        "data": [
          {
            "type": "answers",
            "method": "create",
            "temp-id": "1"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "answers",
      "temp-id": "1",
      "attributes": {
        "url_answer": "https://pinpointhq.com"
      },
      "relationships": {
        "question": {
          "data": {
            "id": "1",
            "type": "questions"
          }
        }
      }
    }
  ]
}
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "answers": {
        "data": [
          {
            "type": "answers",
            "method": "create",
            "temp-id": "1"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "answers",
      "temp-id": "1",
      "attributes": {
        "document_base64_filename": "example.pdf",
        "document_base64_data": "data:application/pdf;base64,...[REDACTED_DATA]..."
      },
      "relationships": {
        "question": {
          "data": {
            "id": "1",
            "type": "questions"
          }
        }
      }
    }
  ]
}
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "answers": {
        "data": [
          {
            "type": "answers",
            "method": "create",
            "temp-id": "1"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "answers",
      "temp-id": "1",
      "attributes": {
        "date_answer": "2020-04-01"
      },
      "relationships": {
        "question": {
          "data": {
            "id": "1",
            "type": "questions"
          }
        }
      }
    }
  ]
}
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "answers": {
        "data": [
          {
            "type": "answers",
            "method": "create",
            "temp-id": "1"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "answers",
      "temp-id": "1",
      "attributes": {},
      "relationships": {
        "answer_options": {
          "data": [
            {
              "type": "answer_options",
              "method": "create",
              "temp-id": "answer-option-1"
            },
            {
              "type": "answer_options",
              "method": "create",
              "temp-id": "answer-option-2"
            }
          ]
        },
        "question": {
          "data": {
            "id": "1",
            "type": "questions"
          }
        }
      }
    },
    {
      "type": "answer_options",
      "temp-id": "answer-option-1",
      "attributes": {
        "text": "Ruby"
      }
    },
    {
      "type": "answer_options",
      "temp-id": "answer-option-2",
      "attributes": {
        "text": "Blue"
      }
    }
  ]
}

Collecting equality monitoring (DEI) information

An array of equality_monitoring_option_ids can optionally be supplied as an attribute of an application. These option IDs relate to the equality monitoring option IDs that can be retrieved with a request to the equality monitoring categories endpoint.

  • All data is optional: In this way you can allow users to supply only those details that they feel comfortable with.
  • Only one option is allowed to be supplied per category: E.g. you cannot supply options that indicate both Male and Female for the gender category.
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]",
      "equality_monitoring_option_ids": ["1","11"]
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      }
    }
  }
}

Source attribution

Optional channel and channel_source attributes can be supplied when creating or updating applications. These allow you to categorise where applicants were sourced from. If these are not supplied then the application will have its channel set to undetermined.

The channel must be one of a predefined list, where as the channel_source can be free text up to 255 characters in length. For a full list of the available channels, see the detailed list of all source attribution channels.

{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Bloggs",
      "email": "[email protected]",
      "channel": "event",
      "channel_source": "Spring marketing campaign"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      }
    }
  }

Add or remove tags

You can add and remove tags on the application. You need to specify the tag name and tag context.

{
  "data": {
    "type": "applications",
    "attributes": {
      "add_tags_with_context": [
        {
          "tag": "Assessment: Passed",
          "context": "assessment"
        },
        {
          "tag": "Background check: Rejected",
          "context": "background_check"
        }
      ]
    }
  }
}
How to apply/remove tags?

Tags in Pinpoint let you categorise and filter candidates and applications. This guide explains how to apply tags correctly via the API so they appear in the right filter groups inside the Pinpoint UI.

How Tags and Categories Work

Every tag in Pinpoint belongs to a tag category (also called a tag group). In the UI, these categories appear as named sections — for example, "Rejection Reasons" or "Skills" — and they power the filter panel.

If you want the tag to be filtrable you must first create it in the UI!

When you apply a tag via the API, you must supply two pieces of information:

FieldWhat it isExample
tagThe name of the tag"Not Qualified"
contextThe identifier for the tag's category"custom_rejection_reasons"

Getting the context right is the critical step — it is what determines which filter group the tag appears under in the UI.

Finding the Right context Value

The context value is derived from the name of the tag category in Pinpoint settings (Settings → Tag Management). The rules are:

  • Custom categories (anything you create): take the category name, lowercase it, replace spaces with underscores, and prefix with custom_. For example:
    • Category named "Rejection Reasons" → context: "custom_rejection_reasons"
    • Category named "Skills" → context: "custom_skills"
    • Category named "Green Skills" → context: "custom_green_skills"
  • The built-in Rejection category: context is always "rejection" (no custom_ prefix).
  • System tags (Internal, Duplicate, Referral, External Recruiter, etc.): these are applied automatically by Pinpoint and cannot be set via the API. Their context is null in API responses.

Tip: The safest way to confirm the correct context for a category is to read back an existing application that already has a tag from that category. The response will include the context value you need (see Reading Tags below).

Reading Tags

Tags are returned as an array in the tags attribute when you fetch an application or job seeker:

Request: GET /api/v1/applications/{id}?extra_fields[applications]=tags

Response (tags field):

"tags": [
  { "context": "custom_rejection_reasons", "name": "Not Qualified" },
  { "context": "custom_skills",            "name": "Ruby" },
  { "context": "rejection",               "name": "Availability" },
  { "context": null,                      "name": "Internal" }
]

The context value in any existing tag response is exactly the value you should pass when writing tags.

Adding Tags

Use a PATCH or PUT request on the resource. You can add one tag at a time or several in one request.

Add a single tag:

PATCH /api/v1/applications/{id}

{
  "add_tag_with_context": {
    "tag": "Not Qualified",
    "context": "custom_rejection_reasons"
  }
}

Add multiple tags at once:

PATCH /api/v1/applications/{id}

{
  "add_tags_with_context": [
    { "tag": "Not Qualified",  "context": "custom_rejection_reasons" },
    { "tag": "Ruby",           "context": "custom_skills" }
  ]
}

The same fields work on job seeker records: PATCH /api/v1/job_seekers/{id}

Removing Tags

PATCH /api/v1/applications/{id}

{
  "remove_tag_with_context": {
    "tag": "Not Qualified",
    "context": "custom_rejection_reasons"
  }
  }

To remove several at once, use remove_tags_with_context with an array, following the same pattern as add_tags_with_context.

Adding Custom Attributes to an Application

📘

Custom Field - IMPORTANT

It is important to read about Custom Fields and their resource_type and field_type and how they must be confirmed before you can create Custom Attributes alongside applications.

custom_attributes created for applications must have be associated with custom_fields that have a resource_type of application. The appropriate value for the new custom_attribute must also align with the field_type of the custom_field.

👍

Adding Custom Attributes to the request body

  • You must add custom_attributes to the relationships section of the request body and give each one a temp-id.
  • These temp-id must match the temp-id that you assign the corresponding custom_attribute that you create in the included section of the request body.
  • The included section is where you will pass all of the attributes and relationships for the custom_attribute, to properly create it along side the application. The only required relationship for the custom_attribute is the custom_field
{
  "data": {
    "type": "applications",
    "attributes": {
      "first_name": "Test",
      "last_name": "User",
      "email": "[email protected]"
    },
    "relationships": {
      "job": {
        "data": {
          "type": "jobs",
          "id": "1"
        }
      },
      "custom_attributes": {
        "data": [
            {
              "type": "custom_attributes",
              "temp-id": "temp-id-1",
              "method": "create"
            }
        ]
      }
    }
  },
  "included": [
    {
      "type": "custom_attributes",
      "temp-id": "temp-id-1",
      "attributes": {
        "varchar_value": "example text value"
      },
      "relationships": {
        "custom_field": {
          "data": {
            "type": "custom_fields",
            "id": "1"
          }
        }
      }
    }
   ]
}
📘

Important

All relationships that also need to be created will need to be in the JSON request body's included section, as seen in the example below. To see this example, please click on the drop down in the top-right corner and select WITH_ANSWERS.

Body Params
data
object
included
array of objects
included
Responses

Updated about 2 months ago

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/vnd.api+json

Updated about 2 months ago