API Reference

Create Application

post https://{subdomain}.pinpointhq.com/api/v1/applications

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"
        }
      }
    }
  }
}

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"
        }
      }
    }
  }

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.

Language
Credentials
Header
URL
Click Try It! to start a request and see the response here!