This guide outlines the setup steps required before you can create jobs or applications via the ATS API.
Missing reference data causes most integration failures. Teams, locations, and employment types must exist in your organization and you need their IDs before making POST requests.
ats:read and ats:write scopes. See Authentication for setup instructions.organizations:write scope if you need to create teams (see below).Jobs require at least one team_id. Define your teams in the Deel App under Organization settings -> Organization -> Groups, or via POST /hris/organization_structures by including a teams array in the request body:
Once created, those teams appear immediately in GET /teams. Retrieve their UUIDs to use in ATS calls:
If teams already exist in your organization, skip the creation step and go straight to GET /teams.
Confirm your token has the correct scopes by calling a lightweight read endpoint.
A 200 response confirms authentication is working. A 401 means your token is missing or invalid. A 403 means your token lacks the ats:read scope.
Jobs require at least one location. Fetch all available locations and store the IDs you will use.
Store the id values for locations you will assign to jobs.
Both job creation and application creation require an employment type.
Some operations, such as advancing an application through an interview plan stage, require a creator_id. This is your HRIS organization user ID.
Store the hris_organization_user_id. You will use it as creator_id when associating applications with interview plan stages.
Departments are optional on jobs but useful for filtering and reporting.
All list endpoints use cursor-based pagination. Use the next_cursor value from a response as the cursor query parameter in the next request.
Check has_more in each response to determine whether additional pages exist.
Fetch and cache reference data (locations, employment types, departments) at integration startup rather than on every request. These values change infrequently.