MakeSure API

The MakeSure API provides a RESTful interface for initiating, managing, and retrieving background screening checks for applicants within external systems. The service is designed to support asynchronous processing of verification workflows, enabling integration into recruitment, onboarding, and compliance platforms.

MakeSure provides a REST API for clients to integrate background checks and screening services directly into their own systems. All resources are accessed via HTTPS from the base URL below.

Base URL

https://api.makesure.com.au/v1

All request and response bodies use JSON. All timestamps follow ISO 8601 format unless otherwise noted.

How it works

The typical integration flow involves four steps:

1

Authenticate

Exchange your Client Key and Secret for a short-lived access token.

2

Create a job

Submit an applicant and a check package. MakeSure returns a jobURL for the applicant to complete.

3

Applicant completes checks

The applicant follows the jobURL to provide any remaining information or documents.

4

Receive updates

Poll the job status endpoint or configure a webhook callback to receive real-time status changes.

Job statuses

A job moves through the following statuses during its lifecycle:

Status	Meaning
Pending	Job created but the applicant has not yet started.
Progress	The applicant has started and checks are underway.
Completed	All checks have been completed and results are available.
Archived	The job has been archived.
Cancelled	The job was cancelled before completion.
Failed	One or more checks could not be completed.

Quick start

This guide walks you through the minimum steps required to create your first job and retrieve its status. You will need your Client Key and Client Secret before starting — contact makesure@makesure.com.au to obtain test credentials.

1

Obtain an access token

Send your credentials to the auth endpoint with the scopes you need. The token returned is short-lived — refresh it every 10 minutes.

POST/v1/auth

// Request
{
  "key": "your-client-key",
  "secret": "your-client-secret",
  "scope": "api.job:write"
}

// Response
{
  "status": "ok",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "response": auth_accepted
}

Token lifetimeTokens expire after approximately 10 minutes. Build your integration to refresh the token proactively before it expires to avoid interrupted requests.

2

Create a job

Submit the applicant details, a hiring manager, and a check package. For testing, use the preset package code 100601.

POST/v1/job/create

// Authorization header required on all requests
Authorization: Bearer <token>

// Minimal request body
{
  "id": "your-internal-job-ref-001",
  "applicant": {
    "email": "jane.smith@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "genderCode": "F",
    "postCode": "2000",
    "notificationType": "EMAIL"
  },
  "application": {
    "job": {
      "positionTitle": "Software Engineer",
      "hiringManager": {
        "firstName": "Alex",
        "lastName": "Jones",
        "email": "alex.jones@yourcompany.com"
      }
    }
  },
  "package": {
    "custom": false,
    "code": "100601"
  }
}

// Response
{
  "status": "Pending",
  "jobId": "your-internal-job-ref-001",
  "jobURL": "https://app.makesure.com.au/job/abc123",
  "refusedChecks": []
}

Send the jobURL to your applicantThe jobURL is the link the applicant must open to complete their checks. Redirect them to it or send it via email or SMS.

3

Check job status

Poll the job status endpoint using the id you provided when creating the job.

GET/v1/job/{id}

// Response when completed
{
  "jobId": "your-internal-job-ref-001",
  "status": "Completed",
  "packageDetails": [
    {
      "12": {
        "dateCompleted": "2024-08-15",
        "checkStatus": "Completed"
      }
    }
  ],
  "jobURL": "https://app.makesure.com.au/job/abc123"
}

Skip polling with webhooksInstead of polling, configure a callback URL in your job creation request and MakeSure will POST status updates to your server automatically. See the Webhooks & callbacks section.

Credentials

To authenticate with the MakeSure API you need two pieces of information: a Client Key and a Client Secret. These are issued per client and are used exclusively to obtain short-lived access tokens — they should never be exposed in client-side code.

Keep credentials secretYour Client Key and Secret should be stored as environment variables or in a secrets manager. Never commit them to source control or embed them in browser-side code.

Obtaining credentials

To request a set of test credentials, send an email to makesure@makesure.com.au. You can discuss billing options, rate limits, and package configurations at the same time.

Third party read-only credentials

MakeSure can issue read-only credentials scoped to api.job:read only. This is useful if you want to grant a third party — such as an analytics tool or an auditor — access to job data without allowing them to create or modify jobs.

Access tokens

Before you can call any other endpoint you must exchange your credentials for an access token. Tokens are short-lived JWTs that carry scope information. Every token is issued for a specific scope — you cannot use a read token to create jobs, and vice versa.

POST/v1/auth

Request body

{
  "key": "string",       // Your Client Key
  "secret": "string",    // Your Client Secret
  "scope": "string"     // One of the scope values below
}

Available scopes

Scope	Grants access to
api.job:write	Create and cancel jobs, create job URLs.
api.job:read	Retrieve job status, list all jobs, list client checks.

Requesting multiple scopesIf your integration both creates and reads jobs, request a token for each scope separately, or consult MakeSure about whether a combined scope is available for your account.

Using the token

Include the token in the Authorization header on every subsequent request using the Bearer scheme:

Authorization: Bearer <token>

Token lifetime & refresh

Tokens are short-lived — they expire after approximately 10 minutes. Your integration should refresh the token before expiry rather than waiting for a 401 response. A straightforward approach is to request a new token every 9 minutes via a background task.

Tampered tokens are blockedIf MakeSure detects that a token has been modified in transit, the token is immediately invalidated and a temporary IP block is issued to the requesting host. Always transmit tokens over HTTPS and never modify the token string.

Create job

Creates a new background check job for an applicant. MakeSure returns a jobURL that the applicant must visit to provide any additional information needed to complete their checks.

POST/v1/job/create

Scope: api.job:write

Idempotency via idThe id field is your internal reference for this job. MakeSure uses it to prevent duplicate entries — if you submit the same id twice, the second request will be rejected. Use a unique identifier from your own system such as an application ID.

Applicant intervention In this casse the applicant needs to visit the jobURL to complete the checks. The jobURL is the link the applicant must open to complete their checks. Redirect them to it or send it via email or SMS.

Request body

{
  "id": "string",                  // required — your internal job reference; this needs to be unique in our system
  "applicant": {
    "email": "string",             // required
    "firstName": "string",         // required
    "lastName": "string",          // required
    "middleName": "string",        // optional — include if known; omitting may cause name mismatch
    "genderCode": "M|F|X",        // required
    "postCode": "string",          // required
    "notificationType": "SMS|EMAIL|ALL|NONE",  // required
    "mobile": "string",           // optional — include country prefix e.g. +61412345678
    "prefName": "string",         // optional — how MakeSure addresses the applicant
    "title": "string",            // optional — e.g. Mr, Ms, Dr
    "street": "string",           // optional
    "suburb": "string",           // optional
    "state": "string",            // optional
    "country": "string",          // optional — full country name
    "countryCode": "string",      // optional — ISO ALPHA-2 e.g. AU
    "phone1": "string",           // optional — additional contact number
    "phone2": "string"            // optional — additional contact number
  },
  "application": {
    "job": {
      "positionTitle": "string",   // required — full role name e.g. "Registered Nurse"
      "jobTitle": "string",        // optional
      "jobLocation": "string",     // optional
      "profitCentre": "string",    // optional — internal position reference
      "officeCode": "string",      // optional — required for multi-ABN entity clients
      "hiringManager": {
        "firstName": "string",    // required
        "lastName": "string",     // required
        "email": "string",       // required
        "title": "string",       // optional
        "prefName": "string",    // optional
        "phone": "string",       // optional
        "mobile": "string",      // optional
        "fax": "string",         // optional
        "country": "string",     // optional
        "countryCode": "string"  // optional — ISO ALPHA-2
      }
    }
  },
  "package": {
    "custom": false,               // false = use a preset code; true = specify checks array
    "code": "100601",              // required if custom is false;this is unique code provided to each API consumer in order to provide preset job checks for applicants; use "100601" for testing
    "title": "string"             // optional — display name for the job
  },
  "duedate": "YYYY-MM-DD",           // optional
  "options": {
    "redirect_url": "string",     // optional — redirect applicant here after completing checks
    "deadline": "YYYY-MM-DD HH:MM:SS",  // optional — applicant must complete before this datetime
    "callback": [
      {
        "url": "string",         // optional — your webhook endpoint
        "state": "Completed|Cancelled|Archived|All",
        "token": "string"        // optional — token MakeSure sends to authenticate the callback
      }
    ]
  }
}

Custom check packages

If package.custom is true, provide a checks array instead of a code.
additionalData is not accepted here, sending the parameter here, will return error message.
Use the Get client checks endpoint to retrieve valid check IDs for your account.

"package": {
  "custom": true,
  "checks": [
    { "id": 12 },
    { "id": 7, "noEmployers": 2 }  // noEmployers: 1–3, for Reference checks or Employment Confirmation checks
  ]
}

Response

{
  "status": "Pending",
  "jobId": "your-internal-job-ref-001",
  "jobURL": "https://app.makesure.com.au/job/abc123",
  "refusedChecks": []
}

Field	Description
status	Initial job status. Always `Pending` on creation.
jobId	The `id` you provided. Use this to retrieve or cancel the job later.
jobURL	The URL the applicant must open to complete their checks. Send this to the applicant immediately.
refusedChecks	Array of check IDs that MakeSure could not add to the job. An empty array means all checks were accepted.

How it works

1

Authenticate

The client is authenticated using the short-lived access token, scope for the token and requested operation are being checked.

2

Create a job

Submit an applicant and a check package. MakeSure returns a jobURL for the applicant to complete.
If notificationType is SMS or EMAIL, an SMS or email is sent to the applicant with the jobURL, if is set to ALL, both are sent, and if is set to NONE, no notification is sent to applicant.

3

Applicant completes checks

The applicant follows the jobURL to provide any remaining information or documents.

4

Processing

The documents and received information are being processed by Makesure and third parties. Such process can take from few minutes to 30 days.

5

Receive updates

Poll the job status endpoint or configure a webhook callback to receive real-time status changes.

Response codes

The API returns standard HTTP status codes. Error responses include a message body explaining what went wrong.

Code	Status	Meaning	Response format
200	OK	Request was successful.	Read the response body.
201	Queued\|Pending	Request was successful. The resource is queued or pending.	{status: 'Queued/Pending',job: { id: <source_id>, data: <job_data>},jobURL:"returned for pending status; will be used by the applicant to complete personal info and add needed documents.",refusedChecks: []}.
400	Bad Request	The request body failed validation. The response body contains field-level errors.	{ status: 'error',errors: ['missing_id', 'source_job_already_existent', 'missing_package_data']} or {status: 'error',error: 'duplicate_check_id'}
401	Unauthorized	The token is missing, expired, or has been tampered with.
403	Forbidden	The token does not have the required scope for this endpoint.	{status: 'error', error: 'access_forbidden'}
404	Not Found	The endpoint or resource does not exist.
500	Internal Server Error	An unexpected error occurred on MakeSure's side.	{status: 'internal_error', code: 'create_package_error'}
429	Throttle error	Too many requests from client.	{ status: 'error',errors: ['too_many_requests']}

Create job prefilled

Identical to Create job but allows you to pre-supply identity documents and additional applicant data on behalf of the applicant. This reduces the number of steps the applicant must complete on the MakeSure portal.

POST/v1/job/create_prefilled

Scope: api.job:write

NCCHC jobs have additional requirementsNationally Coordinated Criminal History Check (NCCHC) jobs require specific fields and documents. See the requirements section below.

Please ensure that the following documents are uploaded and all required information is added before submitting a Nationally Coordinated Criminal History Check (NCCHC) to Makesure:

Commencement of Identity Document: Upload at least one document listed as a ‘Commencement of Identity Document’ in the reference and their document identifiers.
Photographic Identity Document: Upload an identity document containing a photograph from one of the provided documents.
Primary Use in Community Document: Upload at least one document listed as a ‘Primary Use in Community Document’ in the reference and their document identifiers.
Secondary Use in Community Document: Upload at least one document listed as a ‘Secondary Use in the Community Document’ in the reference and their document identifiers.
Passport-Style Photograph: Submit a passport-style photograph of the applicant.
Name Discrepancies: If the names on any of the identity documents differ, provide documentation that demonstrates a link between the differing names as listed in the reference and their document identifiers.

Additional fields vs. Create job

application.job (NCCHC only)

Field	Required	Description
officeCode	NCCHC	Office code for the ABN entity conducting the check. Defaults to Primary Company ABN if omitted.
ncchcconsent	NCCHC	Must be `"1"` to confirm the applicant has consented to the NCCHC.
thirdpartyconsent	NCCHC	`"0"` or `"1"` — whether the applicant consents to sharing results with third parties.

documents array

An array of identity documents to submit on behalf of the applicant. Each entry contains:

Field	Description
code	Document type code. Use `"selfie"` for a passport-style photo, `"consent"` for a signed consent form, or a document code from the Identity documents table (e.g. `"DL"` for driver licence).
image	URL or base64-encoded image of the document.
data	Required for identity documents (not selfie/consent). A structured object with the document's fields — see the Identity documents section for per-document schemas.

"documents": [
  {
    "code": "selfie",
    "image": "https://your-cdn.com/applicant-photo.jpg"
  },
  {
    "code": "DL",
    "image": "https://your-cdn.com/drivers-licence.jpg",
    "data": {
      "FamilyName": "Smith",
      "GivenName": "Jane",
      "BirthDate": "1990-04-15",
      "StateOfIssue": "NSW",
      "LicenceNumber": "12345678"
    }
  }
]

package.checks.additionalData (NCCHC only)

{
  "workPlace": "Sydney Children's Hospital",
  "work_location_state": "NSW",
  "work_location_town": "Randwick",
  "contact_with_children": ""No Vulnerable|Supervised contact|Unsupervised contact"",
  "address": [
    {
      "type": "RESID",           // RESID = current, POST = postal, PREV = previous
      "street": "42 Example St",
      "suburb": "Surry Hills",
      "state": "NSW",
      "postcode": "2010",
      "country": "Australia",
      "startDate": "01/01/2020"
    }
  ],
  "documentsInCurrentName": true
}

NCCHC document checklist

#	Requirement	Notes
1	Commencement of identity document	At least one — codes BC, CC, VI, IM, PP.
2	Photographic identity document	Any document containing a photo of the applicant.
3	Primary use in community document	At least one — see Primary category in Identity documents.
4	Secondary use in community document	At least one — see Secondary category in Identity documents.
5	Passport-style photo (`"selfie"`)	A recent photo of the applicant against a plain background.
6	Name linkage document	Required only if names across documents differ — e.g. Change of Name (NC) or Marriage Certificate (MC).

Full request body

{
  "id": "string",                  // required — your internal job reference; this needs to be unique in our system
  "applicant": {
    "email": "string",             // required
    "firstName": "string",         // required
    "lastName": "string",          // required
    "middleName": "string",        // optional — include if known; omitting may cause name mismatch
    "genderCode": "M|F|X",        // required
    "postCode": "string",          // required
    "notificationType": "SMS|EMAIL|ALL|NONE",  // required
    "mobile": "string",           // optional — include country prefix e.g. +61412345678
    "prefName": "string",         // optional — how MakeSure addresses the applicant
    "title": "string",            // optional — e.g. Mr, Ms, Dr
    "street": "string",           // optional
    "suburb": "string",           // optional
    "state": "string",            // optional
    "country": "string",          // optional — full country name
    "countryCode": "string",      // optional — ISO ALPHA-2 e.g. AU
    "phone1": "string",           // optional — additional contact number
    "phone2": "string"            // optional — additional contact number
  },
  "application": {
    "job": {
      "positionTitle": "string",   // required — full role name e.g. "Registered Nurse"
      "jobTitle": "string",        // optional
      "jobLocation": "string",     // optional
      "profitCentre": "string",    // optional — internal position reference
      "officeCode": "string",      // required 
      "ncchcconsent": "0|1",      // required for NCCHCC checks
      "thirdpartyconsent": "0|1",      // required for NCCHCC checks
      "hiringManager": {
        "firstName": "string",    // required
        "lastName": "string",     // required
        "email": "string",       // required
        "title": "string",       // optional
        "prefName": "string",    // optional
        "phone": "string",       // optional
        "mobile": "string",      // optional
        "fax": "string",         // optional
        "country": "string",     // optional
        "countryCode": "string"  // optional — ISO ALPHA-2
      }
    }
  },
  "documents": {
    "code": "selfie|consent|IdentityDocumentCode",     //find IdentityDocumentCode defined in Identity Documents section
    "image": "image url",              //Document image URL needs to be accessible and downloadable
    "data": "IdentityDocumentData"             // as defined in Identity Documents section
  },
  "package": {
    "custom": false,               // false = use a preset code; true = specify checks array
    "checks": [{
       "id": "check number",  //as obtained from the Get client checks request
       "noEmployers": 2, // noEmployers: 1–3, for Reference checks or Employment Confirmation checks
       "additionalData":{  
          "workPlace": "workPlace",
          "work_location_state": "string",
          "work_location_town": "string",
          "contact_with_children": "No Vulnerable|Supervised contact|Unsupervised contact",
          "address":[{ 
              "type": "RESID|POST|PREV",
              "street": "string",
              "suburb": "string",
              "state": "string",
              "postcode": "string",
              "country": "string",
              "startDate": "dd/mm/yyyy",
              "endDate": "dd/mm/yyyy"             // required only for Previous Addresses
          }],
          "birthDetails":{ 
              "dateYearOnly": "boolean",
              "date": "dd/mm/yyyy|yyyy",
              "town": "string",
              "state": "string",
              "country": "string"
          },
          "documentsInCurrentName": "boolean",
          "previousName":{ 
              "type": "MAIDN|ALIAS|PREVS",
              "firstName": "string",
              "lastName": "string",
              "middleName": "string",     // optional
              "singleNameOnly": "boolean"
          }
       }
    }],
    "code": "string",               // Required only if "custom" is false. A unique code provided to each API consumer in order to provide preset job checks for applicants.
    "title": "string",               // optional - title to be used when referring to the job
  },
  "duedate": "YYYY-MM-DD",           // optional; if you want the job to be created on a specific day. This will result in a response having status: Queued
  "options": {
    "redirect_url": "string",     // optional — redirect applicant here after completing checks
    "deadline": "YYYY-MM-DD HH:MM:SS",  // optional — applicant must complete before this datetime
    "callback": [
      {
        "url": "string",         // optional — your webhook endpoint
        "state": "Completed|Cancelled|Archived|All",  //optional - job status when you want to receive job information thru callback
        "token": "string"        // optional — token MakeSure sends to authenticate the callback
      }
    ]
  }
}

Success Response

Error Response

{
    "status": Pending,     //required; 'Pending' or 'Queued' for the jobs that have duedate
    "jobId": "string"   // Makesure job Identifier 
    "jobURL": "string"   // Makesure jobURL 
    "refusedChecks": "Array"   // Array of refused check IDs
  }

{
    "status": "error",  //required
    "error": "string",  //optional, error message
    "errors": "Array",  //optional, Array of errors
    "message": "string"   //optional

  }

Response codes

The API returns standard HTTP status codes. Error responses include a message body explaining what went wrong.

Code	Status	Meaning	Response format
200	OK	Request was successful.	Read the response body.
201	Queued\|Pending	Request was successful. The resource is queued or pending.	{status: 'Queued/Pending',job: { id: <source_id>, data: <job_data>},jobURL:"returned for pending status; will be used by the applicant to complete personal info and add needed documents.",refusedChecks: []}.
400	Bad Request	The request body failed validation. The response body contains field-level errors.	{ status: 'error',errors: ['missing_id', 'source_job_already_existent', 'missing_package_data']} or {status: 'error',error: 'duplicate_check_id'}
401	Unauthorized	The token is missing, expired, or has been tampered with.
403	Forbidden	The token does not have the required scope for this endpoint.	{status: 'error', error: 'access_forbidden'}
404	Not Found	The endpoint or resource does not exist.
500	Internal Server Error	An unexpected error occurred on MakeSure's side.	{status: 'internal_error', code: 'create_package_error'}
429	Throttle error	Too many requests from client.	{ status: 'error',errors: ['too_many_requests']}

Create AFP job prefilled

Identical to Create job but allows you to pre-supply identity documents and additional applicant data on behalf of the applicant. The goal is to remove the applicant intervention on the MakeSure portal.

Idempotency via id The id field is your internal reference for the verification request. MakeSure uses this value to prevent duplicate submissions once document processing has started.
If you send the same id again after the identity documents have already been submitted and processing is underway, the new request will be rejected.
If processing has not started yet, any previously uploaded documents will be replaced based on the documentType key.
Use a unique identifier from your system, such as an application ID.

POST/v1/job/create_afp

Scope: api.job:write

AFP jobs have additional requirementsFederal Police checks (AFP) jobs require specific fields and documents. See the requirements section below.

Please ensure that the following documents are accessible for upload or all the required information is added before submitting a Federal Police checks (AFP) to Makesure:
Use a combination of the documents(url or information) listed as AFP documents in the Identity Documents section.
The total points for the submitted documents must exceed 100. Please review the points allocated to each type of document within the Identity Documents section.

AFP documents submission The responsibility would lie with your company when submitting the information to ensure that the identity documents provided by the candidate meet the requirements of the check. Makesure will not perform any additional validation checks or generate error messages if the documents do not meet the requirements upon initial review.

Changes in fields vs. Create job

applicant

applicant fields will has supplementary information, and some fields mandatory status changes:

Field	Description
birthDetails	(required) Birth details will be taken from here
addresses	List of addresses; residential is required
previousNames	Previous names list, if applicant has any other names than the birth name
notificationType	Optional, will be set by default to NONE.
email/phone	These fields are optional. You need to set an email/phone number if you want notifications to be sent to applicant.
package.custom	true (for AFP checks only true value is accepted)

identity

An array of identity documents to submit on behalf of the applicant. Each entry contains:

Field	Description
documentType	Document type code. Use `"selfie"` for a passport-style photo, `"consent"` for a signed consent form, or a document code from the Identity documents table (e.g. `"DL"` for driver licence).
totalPoints	Points associated to the documentType. Check Identity Documents
documentNumber	Number/series associated to the document
issuingCountry	Country that released the document
expiryDate	Expiry Date of the document having the format MM-DD-YYYY
verifiedByClient	yes\|no
attachments	Containing a list of documents related to the check: an image/pdf URL or base64-encoded image of the document, mimeType, fileName.

"identity": [
  {
    "documentType": "SELFIE|CONSENT|PP|DL|etc.", 
    "totalPoints": "70", 
    "documentNumber": "AA-1232432334", 
    "issuingCountry": "AU", 
    "expiryDate": "04-29-2026", 
    "verifiedByClient": "yes", 
    "attachments":[{
          "type": "image", 
          "fileName": "photo.jpeg", 
          "mimeType": "image/jpeg", 
          "content": "https://your-cdn.com/photo.jpeg"
    }]
  }
]

package

The package object will always have custom:true. There will be no additionalData sent here, as this information will be passed into identity list.

Field	Description
package.custom	true; for AFP checks only true value is accepted

"package": [
  {
    "custom": "true", 
    "checks": [{, 
        "id": "123", 
        "noEmployers": 2 
    }],
    "callbackUrl": "https://your-callback.com/url"
  }
]

AFP identity documents

#	Requirement	Notes
1	Photographic identity document	Any document containing a photo of the applicant.
2	Applicant consent document
3	100 pts identity documents	A combination of documents listed as AFP documents in the Identity Documents section. The total points for the submitted documents must exceed 100. If you have not sent any identity documents, this validation will not take place.

Minimum requirements for the request body:

{
    "id": "string",               // your internal job reference; this needs to be unique in our system
    "applicant": {
      "firstName": "string",         
      "lastName": "string",          
      "birthDetails":{ 
          "dateOfBirth": "date",  // MM-DD-YYYY format
          "birthCity": "string",  // town/suburb
          "birthCountry": "string"// ISO country code (e.g. AU) or the full country name (e.g. Australia)
      },
      "address":[{                                            // RESIDENTIAL is required
          "type": "RESIDENTIAL",   
          "street1": "string",    // address1 
          "country": "string",    // ISO country code (e.g. AU) or the full country name (e.g. Australia) 
          "startDate": "date"     // format MM-DD-YYYY
      }]
    },
    "application": {
      "job": {
        "positionTitle": "string" // full role name e.g. "Registered Nurse"
      }
    },
    "package": {
      "custom": true,            //always true
      "checks": [{
        "id": "check number"      // as obtained from the Get client checks request
      }],
      "callbackUrl": "string"     // URL where the requester will receive the results
    }
  }

Full request body

{
  "id": "string",                  // required — your internal job reference; this needs to be unique in our system
  "applicant": {
    "email": "string",             // optional
    "firstName": "string",         // required
    "lastName": "string",          // required
    "middleName": "string",        // optional — include if known; omitting may cause name mismatch
    "genderCode": "M|F|X",        // optional
    "postCode": "string",          // optional
    "notificationType": "SMS|EMAIL|ALL|NONE",  // optional - defaults to ALL
    "mobile": "string",           // optional — include country prefix e.g. +61412345678
    "prefName": "string",         // optional — how MakeSure addresses the applicant
    "title": "string",            // optional — e.g. Mr, Ms, Dr
    "street": "string",           // optional
    "suburb": "string",           // optional
    "state": "string",            // optional
    "country": "string",          // optional — full country name
    "countryCode": "string",      // optional — ISO ALPHA-2 e.g. AU
    "phone1": "string",           // optional — additional contact number
    "phone2": "string",            // optional — additional contact number
    "birthDetails":{ 
        "dateOfBirth": "date",  // required — MM-DD-YYYY format
        "birthCity": "string",  // required - town/suburb
        "birthState": "string",  // optional - region/state
        "birthCountry": "string"  // ISO country code (e.g. AU) or the full country name (e.g. Australia)
    },
    "address":[{                                           // RESIDENTIAL is required
        "type": "RESIDENTIAL|POSTAL|PREVIOUS",   
        "street1": "string",     // required - address1 
        "street2": "string",     // optional - address2 
        "suburb": "string",      // optional - town 
        "state": "string",       // optional - region/state (required if AU) 
        "postcode": "string",    // optional - postal code 
        "country": "string",     // ISO country code (e.g. AU) or the full country name (e.g. Australia)
        "startDate": "date",    // required - format MM-DD-YYYY
        "endDate": "date"             // required only for Previous Addresses, format MM-DD-YYYY
    }], 
    "documentsInCurrentName": "boolean",   // optional
    "previousNames":{ 
        "type": "MAIDEN|ALIAS|PREVIOUS",    // required if documents in previous names
        "firstName": "string",      // required
        "lastName": "string",       // required
        "middleName": "string",     // optional
        "singleNameOnly": "boolean" 
    }
  },
  "application": {
    "job": {
      "positionTitle": "string",   // required — full role name e.g. "Registered Nurse"
      "jobTitle": "string",        // optional
      "jobLocation": "string",     // optional
      "profitCentre": "string",    // optional — internal position reference
      "officeCode": "string",      // optional 
      "hiringManager": {
        "firstName": "string",    // optional
        "lastName": "string",     // optional
        "email": "string",       // optional
        "title": "string",       // optional
        "prefName": "string",    // optional
        "phone": "string",       // optional
        "mobile": "string",      // optional
        "fax": "string",         // optional
        "country": "string",     // optional
        "countryCode": "string"  // optional — ISO ALPHA-2 e.g. AU
      }
    }
  },
  "identity": [{                                          //required
    "documentType": "string",     //required - selfie|consent|PP|DL|etc. - find IdentityDocumentCode defined in Identity Documents section
    "totalPoints": "string",              //optional - the document related points - find IdentityDocument Points defined in Identity Documents section
    "documentNumber": "string"             // optional if the attachments contain an image/pdf/base64-encoded data
    "issuingCountry": "string"             // optional ISO 3166 ALPHA-2 e.g. AU
    "expiryDate": "string"             // optional 
    "verifiedByClient": "string"             // optional - yes|no 
    "attachments":[{ 
        "type": "string",  //optional - image/pdf/base64-encoded 
        "fileName": "string",  // optional 
        "mimeType": "string",  // optional 
        "content": "string",  // required - image url, pdf or base64-encoded image content
    }]
  }],
  "package": {
    "custom": true,               //required -  always true
    "checks": [{
       "id": "check number",   //as obtained from the Get client checks request
       "noEmployers": 2, // noEmployers: 1–3, for Reference checks or Employment Confirmation checks
    }],
    "callbackUrl": "string",               // required - URL where the requester will receive the results
    "callbackToken": "string",               // optional - bearer token used to generate bearer token authorization for callback requests
    "code": "string",               // optional - A unique code provided to each API consumer in order to provide preset job checks for applicants.
    "title": "string",               // optional - title to be used when referring to the job
  },
  "duedate": "YYYY-MM-DD",           // optional; if you want the job to be created on a specific day. This will result in a response having status: Queued
  "clientCustomerId": "string",                  // optional — if it exists will be returned to client
  "submittedAt": "string"                  // optional — if it exists will be returned to client
  }

Success Response

Error Response

{
    "status": Pending,     //required; 'Pending' or 'Queued' for the jobs that have duedate
    "jobId": "string"   // Makesure job Identifier 
    "jobURL": "string"   // Makesure jobURL 
    "refusedChecks": "Array"   // Array of refused check IDs
  }

{
    "status": "error",  //required
    "error": "string",  //optional, error message
    "errors": "Array",  //optional, Array of errors
    "message": "string"   //optional

  }

Response codes

The API returns standard HTTP status codes. Error responses include a message body explaining what went wrong.

Code	Status	Meaning	Response format
200	OK	Request was successful.	Read the response body.
201	Queued\|Pending	Request was successful. The resource is queued or pending.	{status: 'Queued/Pending',job: { id: <source_id>, data: <job_data>},jobURL:"returned for pending status",refusedChecks: [array of checks that were not created for the job]}.
400	Bad Request	The request body failed validation. The response body contains field-level errors.	{ status: 'error',errors: ['missing_id', 'source_job_already_existent', 'missing_package_data']} or {status: 'error',error: 'duplicate_check_id'}
401	Unauthorized	The token is missing, expired, or has been tampered with.
403	Forbidden	The token does not have the required scope for this endpoint.	{status: 'error', error: 'access_forbidden'}
404	Not Found	The endpoint or resource does not exist.
500	Internal Server Error	An unexpected error occurred on MakeSure's side.	{status: 'internal_error', code: 'create_package_error'}
429	Throttle error	Too many requests from client.	{ status: 'error',errors: ['too_many_requests']}

Get job status

Get a specific job

GET/v1/job/{id}

Scope: api.job:read

Replace {id} with the job ID you provided when creating the job.

// Response
{
  "jobId": "your-internal-job-ref-001",
  "status": "Completed",
  "jobDetails": {            // Only present for jobs with a Right to Work check
    "dateCompleted": "2024-08-15",
    "visaSubclass": "string",
    "visaExpiryDate": "string",
    "workingRightsRestrictions": "string"
  },
  "packageDetails": [
    {
      "12": {               // Key is the check_id
        "dateCompleted": "2024-08-15",
        "checkStatus": "Completed"
      }
    }
  ],
  "jobURL": "https://app.makesure.com.au/job/abc123",
  "jobURLvalidUntil": "2024-08-15T10:00:00Z"  // Only present if a TTL was set
}

Get all jobs

GET/v1/job/all

Scope: api.job:read

Returns all jobs created by your account. By default, completed jobs are excluded and pending jobs are included.

Query parameters

Parameter	Default	Description
include_completed	`false`	Set to `true` to include jobs with status `Completed`.
include_unassigned	`true`	Set to `false` to exclude jobs that are still `Pending`.

// GET /v1/job/all?include_completed=true
{
  "jobs": [
    { "jobId": 1001, "status": "Completed" },
    { "jobId": 1002, "status": "Progress" }
  ]
}

Cancel job

Cancels a job that is in Pending or Progress state. Once cancelled, a job cannot be reactivated. You must provide a reason for the cancellation.

PUT/v1/job/{id}

Scope: api.job:write

URL parameter

Parameter	Description
id	The job ID you provided at creation time.

Request body

{
  "reason": "Applicant withdrew from the hiring process"
}

Cancellation is irreversibleThere is no undo for a cancelled job. If you need to re-run checks for the same applicant, create a new job with a different id.

Create job URL

Generates a time-limited access URL for an existing job. Use this when you need to share the job portal link with an applicant but want the link to expire after a set period for security reasons.

POST/v1/job/token

Scope: api.job:write

Request body

{
  "id": "your-internal-job-ref-001",
  "ttl": 86400   // Time to live in seconds. 0 or omitted = no expiry.
}

Response

{
  "jobId": "your-internal-job-ref-001",
  "jobURL": "https://app.makesure.com.au/job/abc123?token=xyz",
  "validUntil": "2024-08-16T10:00:00Z"   // UTC+0. Omitted if no TTL was set.
}

Common TTL values3600 = 1 hour · 86400 = 24 hours · 604800 = 7 days. A ttl of 0 or omitting the field generates a URL with no expiry.

Get client checks

Returns all check types available to your account. Use the id values returned here when building custom check packages.

GET/v1/checks

Scope: api.job:read

Response

{
  "response": [
    {
      "id": 7,
      "name": "Employment Reference Check",
      "noEmployers": "3"   // Max employers for reference checks. null if not applicable.
    },
    {
      "id": 12,
      "name": "National Criminal History Check",
      "noEmployers": null
    }
  ]
}

Webhooks & callbacks

Instead of polling the job status endpoint, you can configure MakeSure to POST a payload to your server whenever a job changes status. Callbacks are configured per-job in the options.callback array when creating a job.

Create job and Create Job Prefilled

Create AFP Job Prefilled

Configuring a callback for Create job and Create Job Prefilled

"options": {
    "callback": [
      {
        "url": "https://yourapp.com/webhooks/makesure",
        "state": "Completed",   // Trigger only when job reaches Completed
        "token": "your-secret-token"
      },
      {
        "url": "https://yourapp.com/webhooks/makesure",
        "state": "Cancelled"    // Separate callback for cancellations
      }
    ]
  }

State options

Value	Triggers when
Completed	All checks for the job have been completed.
Cancelled	The job has been cancelled.
Archived	The job has been archived.
All	Any status change occurs.

Callback payload

When triggered, MakeSure sends an HTTP POST to your URL with a JSON body describing the job's current state:

AFP jobs callback payload has different formatPlease check Create AFP job prefilled.

// Example callback payload (Completed)
  {
    "jobId": "your-internal-job-ref-001",
    "status": "Completed",
    "jobURL": "https://app.makesure.com.au/job/abc123",
    "packageDetails": [
      {
        "12": {
          "dateCompleted": "2024-08-15",
          "checkStatus": "Completed"
        }
      }
    ]
  }

Configuring a callback for Create AFP Job Prefilled

AFP jobs have different requirementsFederal Police checks (AFP) jobs require just a callbackUrl set in the package parameters.

"package": {
    "callbackUrl": "https://yourapp.com/webhooks/makesure"
}

State options

Value	Triggers when
Completed	All checks for the job have been completed.
Cancelled	The job has been cancelled.
Archived	The job has been archived.
All	Any status change occurs.

Callback payload

When triggered, MakeSure sends an HTTP POST to your URL with a JSON body describing the job's current state:

POST: /callbackUrl

{
    "status": "string",                  // required — internal status of the job at the time: Completed, Pending, Cancelled, Archived, Failed
    "completedAt": "string",                  // required - date the job_task was Completed
    "providerCaseId": "string",                  // internal Makeure identifier
    "referenceNumber": "string",                  // job identifier used within your system, sent as id in the api call raw data
    "clientCustomerId": "string",                  // clientCustomerId sent in the api call raw data
    "result": {
        "outcome":[{    //required if hasRecord is true - outcome of the Disclosures
            "conviction_date": "string",  
            "court_name": "string",
            "file_number": "string",  
            "offence": "string",
            "sentence": "string",
            "identifiers": "string"
        }],       
        "hasRecord": "boolean"  //required - true|false - false if it has no Disclosures
    },
    "certificate": {
        "available": "boolean",  //required - true|false
        "downloadUrl": "string"  //required - url to download the result
    }
}

Authentication

If you supply a token in the callback configuration, MakeSure includes it as a Bearer token in the Authorization header of the callback request:

Authorization: Bearer your-secret-token

Validate this header in your webhook handler to confirm the request originated from MakeSure and not a third party.

Handling callbacks reliably

Respond quicklyYour endpoint should return a 200 OK as fast as possible. If processing takes time, acknowledge receipt immediately and handle the payload asynchronously in a background worker.

Design for retriesMakeSure may retry the callback if your endpoint does not respond with a 2xx status. Make your handler idempotent — processing the same jobId + status combination twice should not cause side effects.

Testing callbacks locally

During development you can use a tool like ngrok or Cloudflare Tunnel to expose your local server to the internet, then supply the resulting public URL as your callback URL.

Identity documents

When submitting a prefilled job, each identity document requires a code and a structured data object. The tables below list all supported document types by category.

NCCHC

AFP

Document categoriesFor NCCHC checks, documents are classified into four categories: Commencement, Primary, Secondary, and Change of Name. Each category plays a specific role in verifying identity.

Commencement documents

Code	Document	Issuer / Notes
BC	Birth Certificate	Australian State/Territory Births, Deaths and Marriages. Extracts and birth cards are not accepted.
CC	Australian Citizenship Certificate	Department of Home Affairs.
VI	Australian Visa	Department of Home Affairs. Must be supported by a foreign passport.
IM	ImmiCard	Department of Home Affairs.
PP	Australian Passport	DFAT. May be up to 3 years expired if verified via DVS.

Primary documents

Code	Document	Notes
PP	Australian Passport	May be up to 3 years expired if DVS-verified.
DL	Driver licence / learner / provisional	Must include photo. Digital licences must have security features verified.
IM	ImmiCard
FP	Foreign Passport	Must have a valid visa or entry stamp.
PA	Proof of age / photo identity card	Must show name, date of birth, photo, and signature.
SD	Student identity document	Only for persons under 18 with no other primary document.

Secondary documents

Code	Document
MD	Medicare card (Services Australia)
AEC	Electoral enrolment (Australian Electoral Commission)
TFN	Tax File Number (Australian Taxation Office)
BCC	Bank or credit card — signature required; foreign bank cards not accepted
CRC	Credit reference check
FGD	Foreign identity document — non-English docs need NAATI-accredited translation
SCL	Security Guard / Crowd Control photo licence
EoR	Evidence of right to government benefit (DVA or Centrelink)
CPI	Consular photo identity card (DFAT)
PFO	Police Force Officer photo identity card
ADF	Australian Defence Force photo identity card
CMW	Government-issued photo identity card (e.g. Working with Children card)
ASI	Aviation security identification card
MSI	Maritime security identification card
FAL	Firearms licence
AST	Australian secondary or tertiary student photo ID
CAT	Certified academic transcript from an Australian institution
TRR	Trusted referees report
CoI	DFAT Certificate of Identity
DoI	DFAT Document of Identity
UNT	UN Convention Travel Document

Change of name documents

Code	Document	Notes
NC	Change of Name Certificate	Australian State/Territory Government.
MC	Marriage Certificate	Australian State/Territory Government. Church or celebrant certificates not accepted.
NBC	Australian Reissued Birth Certificate

Document data schemas

Australian Birth Certificate

{
  "FamilyName": "string",              // required
  "GivenName": "string",               // optional
  "BirthDate": "YYYY-MM-DD",           // required — ISO 8601
  "RegistrationNumber": "string",       // optional if CertificateNumber is provided
  "CertificateNumber": "string",        // optional if RegistrationNumber is provided
  "RegistrationState": "string",        // required
  "RegistrationDate": "YYYY-MM-DD",      // optional — ISO 8601
  "RegistrationYear": "string",         // optional
  "DatePrinted": "string"                // optional
}

Australian Citizenship Certificate

{
  "FamilyName": "string",         
  "GivenName": "string",            // optional
  "BirthDate": "YYYY-MM-DD",        // optional — ISO 8601
  "AcquisitionDate": "YYYY-MM-DD",  // optional — ISO 8601
  "StockNumber": "string"          
}

Australian Visa

{
  "FamilyName": "string",
  "GivenName": "string",            // optional
  "BirthDate": "YYYY-MM-DD",        // optional — ISO 8601
  "CountryOfIssue": "string",       // optional — ISO 3166 alpha-3
  "PassportNumber": "string"
}

ImmiCard

{
  "FamilyName": "string",
  "GivenName": "string",            // optional
  "BirthDate": "YYYY-MM-DD",        // optional — ISO 8601
  "ImmiCardNumber": "string"
}

Australian Passport

{
  "FamilyName": "string",
  "GivenName": "string",            // optional
  "BirthDate": "YYYY-MM-DD",        // required — ISO 8601
  "Gender": "string",               // optional (M|F|X)
  "TravelDocumentNumber": "string"
}

Australian Driver Licence

{
  "FamilyName": "string",
  "GivenName": "string",            // optional
  "MiddleName": "string",           // optional
  "BirthDate": "YYYY-MM-DD",        // required — ISO 8601
  "StateOfIssue": "string",
  "LicenceNumber": "string",
  "CardNumber": "string"            // optional
}

Foreign Passport

{
  "FamilyName": "string",
  "GivenName": "string",            // optional
  "BirthDate": "YYYY-MM-DD",        // required — ISO 8601
  "CountryOfIssue": "string",       // optional — ISO 3166 alpha-3
  "PassportNumber": "string"
}

Proof of Age

{
  "ReferenceNumber": "string",      // optional
  "ExpiryDate": "YYYY-MM-DD"        // required — ISO 8601
}

Student Identity Document

{
  "ReferenceNumber": "string",      // optional
  "ExpiryDate": "YYYY-MM-DD"        // required — ISO 8601
}

Medicare Card

{
  "FamilyName": "string",
  "GivenName": "string",            // optional
  "CardNumber": "string"
}

Bank / Credit Card

{
  "FamilyName": "string",
  "GivenName": "string",            // optional
  "ExpiryDate": "MM-DD"
}

Tax File Number

{
  "FamilyName": "string",
  "GivenName": "string"             // optional
}

Change of Name Certificate

{
  "FamilyName": "string",
  "GivenName": "string",              // optional
  "BirthDate": "YYYY-MM-DD",
  "RegistrationNumber": "string",     // optional if CertificateNumber is provided
  "RegistrationState": "string",
  "RegistrationYear": "string",       // optional
  "CertificateNumber": "string",      // optional if RegistrationNumber is provided
  "DatePrinted": "string",            // optional
  "RegistrationDate": "string",
  "FamilyName2": "string",
  "GivenName2": "string"              // optional
}

Marriage Certificate

{
  "FamilyName": "string",
  "GivenName": "string",              // optional
  "DateOfEvent": "YYYY-MM-DD",
  "RegistrationNumber": "string",     // optional if CertificateNumber is provided
  "RegistrationState": "string",      // optional
  "CertificateNumber": "string",      // optional if RegistrationNumber is provided
  "RegistrationYear": "string",
  "DatePrinted": "YYYY-MM-DD",
  "RegistrationDate": "YYYY-MM-DD",
  "FamilyName2": "string",
  "GivenName2": "string"
}

Australian Reissued Birth Certificate

{
  "FamilyName": "string",
  "GivenName": "string",              // optional
  "FamilyName2": "string",
  "GivenName2": "string",             // optional
  "BirthDate": "YYYY-MM-DD",
  "RegistrationState": "string",
  "CertificateNumber": "string",      // optional if RegistrationNumber is provided
  "RegistrationNumber": "string",     // optional if CertificateNumber is provided
  "RegistrationDate": "YYYY-MM-DD"    // optional
}

Document categoriesFor PPA checks, documents are grouped into categories based on the number of points assigned to them.

70 points documents

Code	Document	Issuer / Notes
BC	Birth Certificate	Australian State/Territory Births, Deaths and Marriages. Extracts and birth cards are not accepted.
CC	Australian Citizenship Certificate	Department of Home Affairs.
PP	Australian Passport	DFAT. May be up to 3 years expired if verified via DVS.
FP	Foreign Passport	Must have a valid visa or entry stamp.
DOI	DFAT Document of Identity
COI	DFAT Certificate of Identity

40 points documents

Code	Document	Notes
DL	Driver licence / learner / provisional	Must include photo. Digital licences must have security features verified.
CMW	Government-issued photo identity card (e.g. Working with Children card)
ASI	Aviation security identification card
GEI	Government Employee Id
DVA	Australian Veteran Card
CLC	Centrelink Card	Health Care Card or Pensioner Concession Card
AST	Australian secondary or tertiary student photo ID
ADF	Australian Defence Force photo identity card

25 points documents

Code	Document
MD	Medicare card (Services Australia)
PLA	Property lease
BST	Bank Statement
CCC	Credit card — signature required; foreign bank cards not accepted
BCE	Birth certificate extract
BCN	Birth card
MC	Marriage Certificate
DND	Decree Nisi
NC	Name Change Certificate
TAN	Tax notice
AMD	Mortage documents
RA	Rating Authority

20 points documents

Code	Document
UB	Utility bill
RRI	Indigenous reference
FGD	Documents issued outside Australia

Response codes

The API returns standard HTTP status codes. Error responses include a message body explaining what went wrong.

Code	Status	Meaning	What to do
200	OK	Request was successful.	Read the response body.
201	Created	A new resource was created.	Read the response body for the new resource's details.
400	Bad Request	The request body failed validation. The response body contains field-level errors.	Read the error details and fix the request before retrying.
401	Unauthorized	The token is missing, expired, or has been tampered with.	Re-authenticate to obtain a fresh token and retry.
403	Forbidden	The token does not have the required scope for this endpoint.	Request a new token with the correct scope.
404	Not Found	The endpoint or resource does not exist.	Check the URL and the job ID.
500	Internal Server Error	An unexpected error occurred on MakeSure's side.	Report to MakeSure support with the request details and timestamp.
503	Service Unavailable	The API is under maintenance.	Wait and retry. Check MakeSure's status page for updates.

Error response body

For 400 errors, the response body describes which fields failed and why:

// Example 400 response
{
  "status": "error",
  "errors": [
    'missing_id', 'missing_firstname', 'invalid_notification_type', 'source_job_already_existent', etc.
  ]
}

401 with IP blockIf a tampered token triggers the fraud detection system, MakeSure will issue a temporary IP block in addition to invalidating the token. If you suspect this has happened, contact MakeSure support to have the block lifted.

Australian State Codes

Code	Value
ACT	Australian Capital Territory
NSW	New South Wales
NT	Northern Territory
QLD	Queensland
SA	South Australia
TAS	Tasmania
VIC	Victoria
WA	Western Australia