There are 3 main steps to using Ashby's API to create a fully functioning careers page.

Step 1 Get a list of open job postings using the jobPosting.list endpoint.

Step 2 For each job posting in the list, use the jobPosting.info endpoint to get details about a particular job posting, including a specification of the application form.

These application form specifications will allow you to programmatically build forms (for example, HTML forms) that your applicants can fill out.

Step 3 Using these application forms, you can send applications to Ashby using the applicationForm.submit and surveySubmission.create endpoints.

1. Get all open jobs

Use the jobPosting.list endpoint to get a list of your organization's open job postings. You can use this list to create a main careers page that lists opportunities. See the guide on pagination and incremental synchronization for detailed instructions on how to fetch all available data from the endpoint.

2. Get detailed info about a specific job posting

Use the jobPosting.info endpoint to get detailed information about a particular job posting, including a specification of the form used to submit applications.

Form definitions

A form definition looks like this:

{
    "fields": [
        {
            "field": {
                "id": "afc7d3c7-5616-423a-b0db-261888f6f10b",
                "type": "String",
                "path": "_systemfield_name",
                "humanReadablePath": "Name",
                "title": "Name",
                "isNullable": false
            },
            "isRequired": true
        },
        {
            "field": {
                "id": "1c23a4e4-d40a-4574-a3b9-8ec4318421ec",
                "type": "Email",
                "path": "_systemfield_email",
                "humanReadablePath": "Email",
                "title": "Email",
                "isNullable": false
            },
            "isRequired": true
        },
        {
            "field": {
                "id": "fe05b423-e580-4c4b-8a67-32d354bdfe91",
                "type": "File",
                "path": "_systemfield_resume",
                "humanReadablePath": "Resume",
                "title": "Resume",
                "isNullable": false
            },
            "isRequired": true
        }
    ]
}

Each field in fields describes a field that should be in the resulting form, for example a text box or file input. Each field includes its title, a unique id, whether it's a required part of the form, and its type.

The field type can be one of the following values: "String", "Email", "File", "Date", "Number", "Boolean", "LongText", "ValueSelect" (a single-option select field), "MultiValueSelect" (select multiple values), "Phone", "Score", and "SocialLink". For example, for a "String" field you'll likely want an <input> element in your HTML form. For a "File", a file selector, etc.

3. Submit the application

Job postings have 2 types of forms:

The application form. This is the form that is used to submit applications for a job posting. This includes global questions.
Additional survey forms. These are optional forms that can be configured to collect additional information from applicants, such as EEOC questions.

Submit the core application form

When a candidate submits an application for a job posting, you should send the application data to the applicationForm.submit endpoint.

This endpoint requires that request bodies be Content-Type: multipart/form-data. This is to support file uploads (for example, resumes) along with other data for the application.

Suppose, for example, your application form includes a name field, an email field, and resume file field. Each of these fields in the form definition will have a path property (see the example above). This path property is used internally by Ashby to identify the individual fields.

A submission to the applicationForm.submit endpoint for this form might look like this (leaving out the auth header for clarity):

curl --request POST 'https://api.ashbyhq.com/applicationForm.submit' \
--header 'Content-Type: multipart/form-data' \
--form 'applicationForm={"fieldSubmissions":[{"path":"_systemfield_name","value":"Monty Api"},{"path":"_systemfield_email","value":"[email protected]"},{"path":"_systemfield_resume","value":"resume_1"}]}' \
--form 'resume_1=@/path/to/file' \
--form 'jobPostingId=26a4281b-4ab2-4829-b664-7c43d7dbd409' \
--form 'utmData={ "utm_source": "whatever", "utm_campaign": "something" }'

The applicationForm field's value is a JSON string that encodes the applicant's response to each question on the form, identified by the path that was returned on the form definition. The jobPostingId field holds the value of the id for the job posting this application is for.

Note the value for the file field: "resume_1". This value matches another key in this request form: this identifies the file that is being uploaded as a response to the _systemfield_resume question. Note that the identifier resume_1 can be any string you want - it just has to be unique in the request form.

The value of the resume_1 parameter is the actual binary of the file being uploaded (note in this example we use a cURL utility @ that allows specifying a local file path. See the endpoint documentation for an example of using Node to get the file data).

Finally, the utmData parameter is the only optional one here. If you have UTM data that you'd like attached to this application, you can include it here in a JSON-encoded string.

After sending this request, if it's successful you'll receive a response that includes both the original form definition as well as an array of the recorded responses. If there is a problem with the form (for example, if "name" is required but not provided), the response will contain a list of errors.

Submit additional survey forms

After submitting the application form, you can submit additional survey forms using the surveySubmission.create endpoint.

Each survey form has its own form definition, which is returned in the surveyFormDefinitions field of the jobPosting.info response.

Survey forms must be submitted after the application, as each survey form submission requires an applicationId and candidateId which are only generated after a successful application.

First, query the application.info endpoint to get the applicationId and candidateId.
Then, use the surveySubmission.create endpoint to submit the survey form.

A submission to the surveySubmission.create endpoint might look like this (leaving out the auth header for clarity):

curl --request POST \
     --url 'https://api.ashbyhq.com/surveySubmission.create' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
  "candidateId": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
  "applicationId": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
  "surveyFormDefinitionId": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
  "submittedValues": {_systemfield_data_consent_ack: ["data_consent_ack"]},
}
'