API Documentation

Authentication

All API requests require the use of a Bearer token for authentication. This token must be included in the header of every request to the API.

Obtaining a Token

You will receive an API token once your integration is enabled. This token should be included as a Bearer token in the Authorization header as follows:

Authorization: Bearer YOUR_ACCESS_TOKEN

Base URL

All URLs referenced in the documentation have the following base:

https://api.nurserecruiter.com/v1

Endpoints

List Candidates

This endpoint retrieves a list of candidates. You can filter the results based on acquisition dates and paginate through the results. Up to 100 candidates are included per request.

  • URL: /candidates
  • Method: GET

Query Parameters

  • acquired_before (optional): Return only candidates acquired before this date. Format: YYYY-MM-DD.
  • acquired_after (optional): Return only candidates acquired after this date. Format: YYYY-MM-DD.
  • page (optional): Specifies the page of results to retrieve.
  • limit (optional): Specifies the number of results per page, up to a maximum of 100. Default is 100.

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Response

The response will be a JSON list of candidates, including pagination details.

Example Response:

{
  "data": [
    {
      "key": "abc123",
      "first_name": "John",
      "last_name": "Doe",
      "title": "RN",
      "name": "John Doe, RN",
      "location": "San Diego, CA",
      "city": "San Diego",
      "state": "CA",
      "zip": "12345",
      "email": "[email protected]",
      "contact": "(555) 123-1234",
      "resume": {
        "url": "https://api.nurserecruiter.com/v1/resume/90xvgm",
        "filename": "John_Doe.pdf"
      },
      "profession": {
        "name": "Registered Nurse",
        "key": "rn"
      },
      "specialties": [
        {
          "key": "skilled-nursing",
          "name": "Skilled Nursing / Long Term Care",
          "experience_months": 12
        }
      ],
      "accept_travel": true,
      "accept_permanent": true,
      "accept_perdiem": true,
      "accept_remote": true,
      "license_states": [
        "California"
      ],
      "locations": [
        "San Diego, CA",
        "Texas"
      ]
    }
  ],
  "links": {
    "first": "https://api.nurserecruiter.com/v1/candidates?page=1",
    "prev": "https://api.nurserecruiter.com/v1/candidates?page=1",
    "next": "https://api.nurserecruiter.com/v1/candidates?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "https://api.nurserecruiter.com/v1/candidates",
    "per_page": 100,
    "to": 100
  }
}

Download Resume

This endpoint allows for the downloading of a candidate’s resume.

  • URL: /resume/{id}
  • Method: GET

Path Parameters

  • id: The unique identifier of the candidate whose resume you wish to download.

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Response

The response will be the resume file in the format stored (.pdf, .doc, etc.), served with the appropriate Content-Type and Content-Disposition to facilitate downloading.

Usage Examples

List Candidates

Here’s how you might use curl to request the first page of candidates acquired after January 1, 2024:

curl -X GET "https://api.nurserecruiter.com/v1/candidates?acquired_after=2024-01-01&page=1" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json"

Download a Resume

Here’s how you might use curl to download a candidate’s resume:

curl -X GET "https://api.nurserecruiter.com/v1/resume/123" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -o "John_Doe_Resume.pdf"