Documentation :: LocumJobsOnline.com

LocumJobsOnline API v2.0

Job Imports

The job imports resource is used to manage bulk job posting.

When importing jobs to LocumJobsOnline, the client posts a single request containing all of the jobs that should be posted, along with optional configurations for the import. The server accepts that request and places the import into a queue for processing. The processing may be delayed depending on how busy the server is, and the amount of time to process the import may depend on the number of jobs being posted and additional factors. Because of the asynchronous nature of import processing, there are two workflows available for determining when the import is complete: callback (suggested) and polling.

Callback workflow

When creating a job import, you can optionally provide a callbackUrl parameter. When processing of your job import completes, LocumJobsOnline will send a POST request to your provided callbackUrl containing the results of the import.

    sequenceDiagram
        box HTTP
            participant Client
            participant Server
        end
        box Imports
            participant Queue
        end
        Client->>Server: POST /api/v2.0/job-imports
        Server->>+Queue: Queue for processing
        Server-->>Client: 202 Accepted
        Note over Client,Server: Server responds immediately, letting
Client know import is queued Queue->>-Server: Done processing Server->>Client: POST {callbackUrl} Note over Client,Server: Server notifies Client that import is
complete via provided webhook

Polling workflow

After initially creating the job import, it will be up to you to poll the server periodically to determine when an import is complete.

    sequenceDiagram
        box HTTP
            participant Client
            participant Server
        end
        box Imports
            participant Queue
        end
        Client->>Server: POST /api/v2.0/job-imports
        Server->>+Queue: Queue for processing
        Server-->>Client: 202 Accepted
        Note over Client,Server: Server responds immediately, letting
Client know import is queued Client->>Server: GET /api/v2.0/job-imports/{id} Server-->>Client: {"status": "pending", ...} Note over Client,Server: Client requests status update before
import is complete Queue->>-Server: Done processing Client->>Server: GET /api/v2.0/job-imports/{id} Server-->>Client: {"status": "complete", ...} Note over Client,Server: Client requests status update after
import is complete

The job import object

The job import object represents a requested job import for your account in the system.

Attributes


idstring

The ID of the job import.


completedAtdate-time

The date/time when the job import was completed, or null if it is not complete.


requestedAtdate-time

The date/time when the job import was requested.


resultsobject

The import results once the import has been completed, or null if it is not complete.


statusenum

The status of the job import.

Possible enum values:
  • pending
  • running
  • complete


Example

{
    "id": "3ShBu2LHxCgxJtFtc7yOY",
    "completedAt": null,
    "requestedAt": "2024-03-02T11:00:54.000000Z",
    "results": null,
    "status": "pending"
}

The job import results object

The job import results object represents the results of a requested job import, including summary counts and detailed errors for any failures.

Attributes


addedinteger

The number of processed jobs that were not found in your account, and added.


deletedinteger

The number of jobs that were deleted.


errorslist<object>

A list of errors that occurred during this import, aggregated by job.


failedinteger

The number of processed jobs that failed to import (see errors for details).


processedinteger

The total number of processed jobs.


unchangedinteger

The number of processed jobs that were found in your account, but had no changes.


updatedinteger

The number of processed jobs that were found in your account and updated.


Example

{
    "added": 48,
    "deleted": 0,
    "errors": [
        {
            "index": 227,
            "messages": [
                "Job ID is missing"
            ],
            "referenceNumber": null
        },
        {
            "index": 3142,
            "messages": [
                "State is invalid. Value passed was: MC"
            ],
            "referenceNumber": "pAQT29bmBL7H"
        },
        {
            "index": 3178,
            "messages": [
                "Zip is invalid. Value passed was: 0"
            ],
            "referenceNumber": "q3IVj4CLstkO"
        }
    ],
    "failed": 3,
    "ignoredValues": [],
    "processed": 4416,
    "unchanged": 4343,
    "updated": 22
}

The job import error object

The job import error object represents a failed job encountered during a requested job import, and coinciding error messages leading to that failure.

Attributes


indexinteger

The index of the job within the jobs list provided in the import.


messageslist<string>

A list of individual error messages for the job.


referenceNumberstring

The referenceNumber of the associated job provided in the import, or null if it was missing.


Example

{
    "index": 3142,
    "messages": [
        "State is invalid. Value passed was: MC"
    ],
    "referenceNumber": "mqnQS38eLwnz"
}

Create a job import

POST https://www.locumjobsonline.com/api/v2.0/job-imports

URL Parameters


No parameters.

Body Parameters


callbackUrl optional url

A webhook URL that you control. An HTTP POST request will be made to this URL when the import is complete. The payload of this request will be identical to the response when retrieving the job import.


deleteJobs optional boolean

Whether or not to delete all other preexisting jobs that are not found in the provided jobs for this import.

The default is false.


jobs REQUIRED list<object>

A list of job objects to import.


Example Request

POST https://www.locumjobsonline.com/api/v2.0/job-imports
{
    "callbackUrl": "https://www.example.com/webhooks/job-import-completed",
    "deleteJobs": false,
    "jobs": [
        {
            "referenceNumber": "u9FE7VIZ",
            "title": "Job Title",
            "city": "Lancaster",
            "state": "PA",
            "postalCode": "17603",
            "description": "Text or HTML describing this job",
            "requirements": "Text or HTML describing the requirements for this job",
            "license": "MD",
            "specialty": "Critical Care",
            "shiftType": "evening",
            "shiftsPerWeek": 4,
            "hoursPerShift": 12,
            "payAmountMin": "737.00",
            "payAmountMax": "913.00",
            "payFrequency": "Hourly",
            "employmentType": [
                "Part-Time",
                "Locum Tenens"
            ],
            "durationLength": 13,
            "durationUnit": "week",
            "startDate": "2024-03-02",
            "benefits": "Text or HTML describing the benefits for this job"
        }
    ]
}

Example Response

{
    "data": {
        "id": "44eJr7YHDO9PqC834E_q5",
        "completedAt": null,
        "requestedAt": "2024-03-02T11:00:54.000000Z",
        "results": null,
        "status": "pending"
    },
    "links": {
        "self": "https://www.locumjobsonline.com/api/v2.0/job-imports/44eJr7YHDO9PqC834E_q5"
    }
}

Retrieve a job import

GET https://www.locumjobsonline.com/api/v2.0/job-imports/:id

URL Parameters


id REQUIRED string

The ID of the job import.


Query Parameters


No parameters.

Example Request

GET https://www.locumjobsonline.com/api/v2.0/job-imports/I6TkZPHWvRXKFRwOLp6gE

Example Response

{
    "data": {
        "id": "I6TkZPHWvRXKFRwOLp6gE",
        "completedAt": null,
        "requestedAt": "2024-03-02T11:00:54.000000Z",
        "results": null,
        "status": "pending"
    },
    "links": {
        "self": "https://www.locumjobsonline.com/api/v2.0/job-imports/I6TkZPHWvRXKFRwOLp6gE"
    }
}