Introduction

Welcome to the Staffing Referrals API! You can use our API to manage referrals, ambassadors, and candidates.

The API is designed to be RESTful and returns data in the JSON format. Parameters are passed as simple HTTP parameters. The API is accessible by any system that can make HTTP requests and parse JSON.

We have examples in Shell and Ruby. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

If you need a feature we don't currently support, please contact your account executive!

With these examples, replace `example.staffingreferrals.com` with the specific Staffing Referals domain for your organization (e.g., `my-agency.staffingreferrals.com`, `referrals.my-agency.com`).

Authentication

require 'curb' # Curl access in ruby

http = Curl.get('https://example.staffingreferrals.com/api/v1/ENDPOINT_HERE', PARAMS) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

# With shell, you can just pass the correct header with each request
curl "https://example.staffingreferrals.com/api/v1/ENDPOINT_HERE" \
  -H "Authorization: YOUR_TOKEN_HERE"

Staffing Referrals allows certain admin accounts to access the API. It uses API access tokens to allow access to the API. Please contact your account executive to set up an account and obtain your token.

Staffing Referrals expects for the access token to be included in all API requests to the server in a header that looks like the following:

Authorization: YOUR_TOKEN_HERE

You must replace YOUR_TOKEN_HERE with your access token.

General Return Structure

The Staffing Referrals API will return a JSON object with status and either data or message elements. When the request was successful, the status will be "success" and the relevant data will be provided. A message may sometimes be provided. For example:

{"status":"success", "message":"Sometimes given", "data":{"id":10,"status":"Lead",...}}

/* Example success */
{
  "status":"success",
  "message":"Sometimes given",
  "data":[
    {
      "id":10,
      "status":"Lead",
      ...
    }
  ]
}

In the event of an error, the returned status will be "error" and the message will indicate what went wrong. For example:

{"status":"error", "message":"Invalid status"}

/* Example error */
{
  "status":"error",
  "message":"Invalid status"
}

Common ATS Syncing Usage

This API is intended to be used when Staffing Referrals does not have an integration with your ATS. The two core ideas are Syncing Applicants/Referrals and Inviting Ambassadors.

Syncing Applicants/Referrals

Terminology

The Staffing Referrals data model is based on the idea of tracking "referrals" where each "referral" references two users: the applicant and the ambassador. All of the people who interact with the system are users (admins, recruiters, ambassadors, and applicants), and there is more flexbility within Staffing Referrals than most ATSes. In the website, this complexity is largely hidden, and referrals and their applicant users are largely presented as a single entity. When interacting with this API, however, the two entities are distinct.

Depending on the "ambassador" user, a "referral" could be two things:

Direct Applicant: If the referral's ambassador is the same as the referral's recruiter, then this person applied directly with a link shared by the recruiter. It's not really a referral because there is no distinct ambassador involved, and typically this wouldn't qualify for an ambassador bonus.
An Ambassador Referral: If the referral's ambassador user is not a recruiter, then this applicant can be considered as referred by the ambassador user. If 'is_referral_lead' is set to true, then the ambassador explicitely referred this person. Otherwise, the applicant applied on a link shared via email, text, or on social media.

Most companies will want to sync Applicants/Referrals from Staffing Referrals into their ATS. It is also advised to sync changes in status back to Staffing Referrals. Some companies find benefit in identifying existing applicants with referrals that exist in their ATS and then importing those into Staffing Referrals.

Pulling Applicants and Referrals from Staffing Referrals into the ATS

While it is possible for recruiters to use Staffing Referrals to contact users who have applied or been referred, it's usually best to pull all Applicants and Referrals into your ATS, and have them use their normal workflow. The Get All Referrals endpoint is intended to allow you to pull all new Applicants/Referrals by providing a since parameter of the last time the system pulled referrals.

Each referral will have an applicant whose information must be used to check for their presence in the ATS. Staffing Referrals uses the following keys in order of priority when attempting to match users between systems: ats_id, email, and phone, and it is suggested that your integration do the same. If the applicant user is not found within the ATS, then it should be created.

The easiest method to allow status tracking back into Staffing Referrals is to store the referral's id within the ATS. The Update User endpoint does allow you to set the ats_id within Staffing Referrals, but this is not required.

If the referral's ambassador user is the same as the recruiter, then this was a direct applicant, and should be treated as someone who applied directly to the recruiter. If the ambassador user is not the recruiter, then most integrations will attempt to match or load the ambassador user into the ATS using similar logic to the applicant user, and credit should be given to the ambassador for referring their friend, however that is handled in your ATS.

Sending Applicant Referral Status from the ATS back into Staffing Referrals

Staffing Referrals tracks the status of each lead and should be notified of status changes within the ATS. It is recommended that you store the referral id from Staffing Referrals for each user in your ATS that is being worked as a lead. With that, call Update Referral to update the status within Staffing Referrals.

Importing Applicants with Referrals from the ATS into Staffing Referrals

Mining your ATS for existing referrals and then importing them into Staffing Referrals allows your ambassadors to track status, and engages the ambassadors to prompt them to refer more people. The Create a Referral endpoint will look up or create the applicant and ambassador users as needed, and then assign credit for a referral if allowed. You will need to provide a recruiter_id to assign these people to, and if not otherwise determined, you can look it up with the Get All Users endpoint by providing a role_name parameter of recruiter. If your admins are also functioning as recruiters, a second call with role_name of admin will provide them.

Inviting Ambassadors

Most companies will export their initial set of Ambassadors to spreadsheets for importing into Staffing Referrals to be invited during the onboarding process. It is also possible to do this via API. Regardless, it is suggested to have this process occur over weeks or months to provide your team the ability to fine tune communications based on response, not overload your recruiters with too much activity at once, and to not overload the Staffing Referrals system.

Regardless of how the initial data is loaded, most integrations should identify users who need to be invited as ambassador on an ongoing basis.

Inviting Contacts from the ATS to be Staffing Referrals Ambassadors

Whether inviting a large number of users during onboarding or inviting new users as they become available in the ATS, they should be invited via the Send Invitation endpoint and marked within your ATS as having been invited. You can store the staffing referrals user ID in your ATS (recommended), or provide your ATS ID. Please do not attempt to send multiple synchronous requests.

Telling Staffing Referrals to Stop Contacting an Ambassador

If a candidate should no longer be contacted, update their status to be inactive with the Update User endpoint.

Syncing Ambassador Metadata into the ATS from Staffing Referrals

If you want to store information about invited ambassadors (their dashboard link, their sharable referral link, etc), it is best to store this information when it is returned from the Send Invitation call.

The API can also be used to determine which ambassadors have accepted their invitation and engaged with the system (is_accepted in user data, and can filter Get All Users based on this).

Handling Duplicates

Staffing Referrals will use three pieces of information to check for existing users before creating a new one: ats_id, email, and phone. Because of this duplicate prevention, these is no automatic deduping process. There is a manual deduplication process within the Staffing Referrals website that will merge two users if they have differing ats_id, email, and phone. If your ATS has detected a duplicate, it is suggested to Update the duplicate user to status of inactive within Staffing Referrals.

Pagination

Certain requests that might return an extremely large number of objects will be paginated. Currently, these are Get All Users and Get All Referrals. The maximum number of records that will be returned in a single request is 1000. If you'd like a smaller number of records per request, you can add the optional page_size parameter.

/* Example */
{
  "status":"success",
  "data":[ ... ],
  "num_records_returned":1000,
  "num_records_total":38798,
  "num_records_remaining":37798,
  "num_pages_remaining":38,
  "page_index":0,
  "page_size":1000
}

Pagination Response

If your response is paginated, a number of additional values are returned.

Value	Description
num_records_returned	Number of records returned in this response.
num_records_total	Total number of records across all pages.
num_records_remaining	Number of records remaining after the current page.
num_pages_remaining	Number of pages remaining after the current page.
page_index	Index of the page currently being returned. 0-based.
page_size	Size of the page currently being returned. Max 1000.

Request Parameters for Pagination

The response of all requests that can be paginated must be checked for the presence of additional pages. If present, the requesting software should issue requests for each page until num_pages_remaining is 0 by passing in a page_index parameter.

Parameter	Description
page_index	The 0-based index of the desired page. Default is 0.
page_size	The number of records desired per page. Default and max are both 1000.

Referrals

Get All Referrals

require 'curb' # Curl access in ruby

http = Curl.get('https://example.staffingreferrals.com/api/v1/referrals', {}) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/referrals" \
  -H "Authorization: YOUR_TOKEN_HERE"

{
  "status":"success",
  "data":[
    {
      "id":10,
      "ats_id":"12345",
      "status":"Lead",
      "created_at":"2001-02-02 21:05:06 UTC",
      "updated_at":"2001-02-02 21:05:06 UTC",
      "is_manual":false,
      "is_referral_lead":true,
      "has_resume":false,
      "previous_referral_ids":"",
      "campaign":{
        "id":48,
        "name":"Sandbox Campaign",
        "status":"Live",
        "minimum_term":null,
        "minimum_term_units":null,
        "applicant_bonus":"$500",
        "ambassador_bonus":"$42",
      },
      "applicant":{
        "id":37,
        "ats_id":"abc123",
        "status":"Active",
        "email":"immanuel@windlervandervort.info",
        "first_name":"Candy",
        "last_name":"Date",
        "phone":null,
        "job_title":null,
        "properties":{
          "Healthcare Professional":"yes",
        },
      },
      "ambassador":{
        "id":36,
        "ats_id":"xyz123",
        "status":"Active",
        "email":"bailey.wiza@mosciskimuller.co",
        "first_name":"Pro",
        "last_name":"Motor",
        "phone":null,
        "properties":{
          "Healthcare Professional":"yes",
        },
      },
      "recruiter":{
        "id":35,
        "ats_id":"42",
        "status":"Active",
        "email":"rosalyn@leuschke.org",
        "first_name":"Recruity",
        "last_name":"Recruiter",
        "phone":null
      },
      "opportunity":{
        "id":37,
        "message":"An Optional Opportunity."
      }
    }
  ]
}

This endpoint retrieves all referrals, optionally filtered to only get recently updated or created ones. This response will be paginated.

HTTP Request

GET https://example.staffingreferrals.com/api/v1/referrals

Query Parameters

Parameter	Description
since	An optional ISO-8601 formatted date to provide a lower bound for updates that you are interested in. For example, if you want all referrals created or updated since noon on the Fourth of July in 2017 Denver Time, use `2017-07-04T12:00:00-07:00`.
ambassador_id	An optional USER_ID, when provided will filter referrals credited to this ambassador.
applicant_id	An optional USER_ID, when provided will look up the active referral for this applicant.
page_index	Optional page index. See pagination.
page_size	Optional page size. See pagination.

Update Referral

require 'curb' # Curl access in ruby

http = Curl.post('https://example.staffingreferrals.com/api/v1/referrals/10',
                 {status: "ineligible"}) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/referrals/10" \
  -H "Authorization: YOUR_TOKEN_HERE" \
  -d "status=ineligible" \
  -X POST

{
  "status":"success",
  "data":{
    "id":10,
    "ats_id":"12345",
    "status":"Ineligible",
    "created_at":"2001-02-02 21:05:06 UTC",
    "updated_at":"2001-02-02 21:05:06 UTC",
    "is_manual":false,
    "is_referral_lead":true,
    "has_resume":false,
    "previous_referral_ids":"",
    "campaign":{
      "id":48,
      "name":"Sandbox Campaign",
      "status":"Live",
      "minimum_term":null,
      "minimum_term_units":null,
      "applicant_bonus":"$500",
      "ambassador_bonus":"$42",
    },
    "applicant":{
      "id":37,
      "ats_id":"abc123",
      "status":"Active",
      "email":"immanuel@windlervandervort.info",
      "first_name":"Candy",
      "last_name":"Date",
      "phone":null,
      "job_title":null,
      "properties":null
    },
    "ambassador":{
      "id":36,
      "ats_id":"xyz123",
      "status":"Active",
      "email":"bailey.wiza@mosciskimuller.co",
      "first_name":"Pro",
      "last_name":"Motor",
      "phone":null
    },
    "recruiter":{
      "id":35,
      "ats_id":"42",
      "status":"Active",
      "email":"rosalyn@leuschke.org",
      "first_name":"Recruity",
      "last_name":"Recruiter",
      "phone":null
    }
  }
}

This endpoint updates a specific referral.

Referral bonus amounts less than 0 or above the campaign's defined limit will be auto corrected to the nearest valid amount. An error will not be returned.

HTTP Request

POST https://example.staffingreferrals.com/api/v1/referrals/REFERRAL_ID

URL Parameters

Parameter	Description
REFERRAL_ID	The ID of the referral
status	One of `"lead"`, `"contacted"`, `"placed"`, `"awaiting_payment"` (This corresponds to the "Approve" tab for admins, and is dispayed as "Awaiting Payment Approval" to admins, and "Placed" to ambassadors), `"paid"`, or `"ineligible"`.

Response

If successful, the API will respond with the details of the referral. See example to the right.

Create a Referral

require 'curb' # Curl access in ruby

http = Curl.post('https://example.staffingreferrals.com/api/v1/referrals',
                 { ats_id: '12345',
                   recruiter: {
                     email: 'recruiter@email.com',
                   },
                   ambassador: {
                     email: 'ambassador@email.com',
                     first_name: 'Anne',
                     last_name: 'Ambassador',
                     phone: '505-555-5555',
                     ats_id: 'abc123',
                   },
                   applicant: {
                     email: 'applicant@email.com',
                     first_name: 'Andrew',
                     last_name: 'Applicant',
                     phone: '505-555-1234',
                     ats_id: 'xyz123',
                   }
                 }) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/referrals/10" \
  -H "Authorization: YOUR_TOKEN_HERE" \
  -d "ats_id=12345&recruiter[email]=recruiter@email.com&ambassador[email]=ambassador@email.com&ambassador[first_name]=Anne&ambassador[last_name]=Ambassador&ambassador[phone]=505-555-5555&ambassador[ats_id]=abc123&applicant[email]=applicant@email.com&applicant[first_name]=Andrew&applicant[last_name]=Applicant&applicant[phone]=505-555-1234&applicant[ats_id]=xyz123" \
  -X POST

{
  "status":"success",
  "data":{
    "id":11,
    "ats_id":"12345",
    "status":"Lead",
    "source":"Your ATS",
    "created_at":"2018-02-02 21:05:06 UTC",
    "updated_at":"2018-02-02 21:05:06 UTC",
    "is_manual":false,
    "is_referral_lead":true,
    "has_resume":false,
    "previous_referral_ids":"",
    "campaign":{
      "id":48,
      "name":"Employee Referral Program",
      "status":"Live",
      "minimum_term":null,
      "minimum_term_units":null,
      "applicant_bonus":"$500",
      "ambassador_bonus":"$42",
    },
    "applicant":{
      "ats_id":"abc123",
      "id":43,
      "status":"Active",
      "email":"applicant@email.com",
      "first_name":"Andrew",
      "last_name":"Applicant",
      "phone":"505-555-1234",
      "job_title":null
    },
    "ambassador":{
      "id":42,
      "ats_id":"xyz123",
      "status":"Active",
      "email":"ambassador@email.com",
      "first_name":"Anne",
      "last_name":"Ambassador",
      "phone":"505-555-5555"
    },
    "recruiter":{
      "id":35,
      "ats_id":"42",
      "status":"Active",
      "email":"recruiter@email.com",
      "first_name":"Recruity",
      "last_name":"Recruiter",
      "phone":null
    }
  }
}

This endpoint creates a manual referral. If the applicant is not in the system (looked up via ats_id, email, and then phone), then it will be created. If the applicant is in the system, then a new referral will be created if appropriate (for instance, they are an ambassador applying directly to a recruiter for a job, or they are applying more than 90 days after they've applied before).

If the ambassador is not in the system (looked up via ats_id, email, and then phone), then they are also created and an invitation email is sent.

Referral bonus amounts less than 0 or above the campaign's defined limit will be auto corrected to the nearest valid amount. An error will not be returned.

HTTP Request

POST https://example.staffingreferrals.com/api/v1/referrals

URL Parameters

Parameter	Required	Description
ats_id		The ID of the referral in your ATS.
source		The source of the referral.
send_emails		Defaults to false. IF TRUE: trigger all of the usual emails as if an ambassador made the referral normally. It is intended for integrations that interact directly with ambassadors. Alerts will be sent to the recruiter and all admins about the new lead. The ambassador will be sent an email thank-you with a link to their dashboard for tracking purposes. The applicant will be sent an email asking for more information and getting them connected to the recruiter. IF FALSE: ambassadors will be sent the "External Ambassador Greeting" email giving them access to SR to manage their referrals and invite more people.
recruiter[email]	Required when the ambassador doesn't exist	The email of the recruiter. If this is provided for an existing ambassador, it will be ignored.
recruiter[use_default_if_not_found]		Set to true to have a failed lookup use the company's configured default recruiter. If set to true, the recruiter[email] field becomes optional.
ambassador[email]	Always Required	The email of the ambassador. If they exist, no further ambassador information is required.
ambassador[first_name]	Required when the ambassador doesn't exist	The first name of the ambassador.
ambassador[last_name]		The last name of the ambassador.
ambassador[phone]		The phone of the ambassador.
ambassador[ats_id]		The ID of the ambassador entity in your ATS.
applicant[email]	One of 'email', 'phone', or 'email_or_phone' required	The email of the applicant.
applicant[phone]	One of 'email', 'phone', or 'email_or_phone' required	The phone of the applicant.
applicant[email_or_phone]	One of 'email', 'phone', or 'email_or_phone' required	If your system only has a generic contact field, SR will parse an email or phone number.
applicant[first_name]	Always Required	The first name of the applicant.
applicant[last_name]		The last name of the applicant.
applicant[ats_id]		The ID of the applicant entity in your ATS.
applicant[job_title]		The job title of the applicant.

Response

If successful, the API will respond with the details of the referral. See example to the right.

New Referral Webhook


{
  "id": 43906,
  "status": "Follow Up",
  "source": null,
  "created_at": "2023-12-15 21:27:05 UTC",
  "updated_at": "2023-12-15 21:27:05 UTC",
  "is_manual": false,
  "is_referral_lead": true,
  "has_resume": false,
  "previous_referral_ids": "",
  "ats_id": null,
  "campaign": {
    "id": 230,
    "name": "Sandbox Campaign",
    "status": "Live",
    "minimum_term": "",
    "minimum_term_units": "",
    "applicant_bonus": "$50",
    "ambassador_bonus": "$100",
    "is_bonus_per_hour": false
  },
  "applicant": {
    "id": 515930,
    "status": "Active",
    "source": null,
    "email": "tes123321@yopmail.com",
    "first_name": "Test",
    "last_name": "Candidate",
    "phone": "",
    "ats_id": null,
    "job_title": null,
    "properties": {}
  },
  "ambassador": {
    "id": 515929,
    "status": "Active",
    "source": null,
    "email": "test775592@yopmail.com",
    "first_name": "Test",
    "last_name": "Ambassador",
    "phone": "",
    "ats_id": null,
    "job_title": null,
    "properties": {},
    "is_accepted": true
  },
  "recruiter": {
    "id": 515284,
    "status": "Active",
    "source": null,
    "email": "test-recruiter@yopmail.com",
    "first_name": "Text",
    "last_name": "Recruiter",
    "phone": "",
    "ats_id": "39638",
    "is_accepted": true
  }
}

Any admin can configure this webhook on the settings page. When a new Referral object is created in Staffing Referrals, an HTTP POST will immediately be made to the configured URL. All data related to the Referral will be passed as JSON in the format shown to the right.

An admin may configure an optional HTTP header to be passed along with the callback HTTP request.

Your webhook handler should return 2xx series HTTP status (like 200 OK) when successful.

Any other outcome, including server 404 or 500 errors will result in a delayed retry. It will wait an exponentially increasing number of minutes (1, 2, 4, ...) before trying again, up to a maximum of 10 attempts.

Users

Get All Users

require 'curb' # Curl access in ruby

http = Curl.get('https://example.staffingreferrals.com/api/v1/users', {}) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/users" \
  -H "Authorization: YOUR_TOKEN_HERE"

{
  "status":"success",
  "data":[
    {
      "id":149,
      "ats_id":"42",
      "status":"Active",
      "email":"hester_ziemann@metz.name",
      "first_name":"Recruity",
      "last_name":"Recruiter",
      "phone":null,
      "is_accepted":true,
      "campaign_id":10,
      "accept_url":"https://example.staffingreferrals.com/accept/2Gp36qA6zZyR478UItgA",
      "join_url":"https://example.staffingreferrals.com/join/rrecruiter",
      "apply_url":"https://example.staffingreferrals.com/apply/rrecruiter",
      "is_public_recruiter":true,
      "created_at":"2018-03-07 23:34:02 UTC",
      "updated_at":"2001-02-02 21:05:06 UTC",
      "role_name":"recruiter"
    },
    {
      "id":150,
      "ats_id":"xyz123",
      "status":"Active",
      "email":"erick@rueckerstrosin.name",
      "first_name":"Pro",
      "last_name":"Motor",
      "phone":null,
      "is_accepted":true,
      
      "campaign_id":10,
      "accept_url":"https://test-company.staffingreferrals.com/enter/DExkoPmQZiUVTjHh1pHL",
      "apply_url":"https://test-company.staffingreferrals.com/apply/pmotor",
      "recruiter_id":30,
      "recruiter_email":"recruiter@example.com",
      "recruiter_name":"Recruity Recruiter",
      "created_at":"2018-03-07 23:34:02 UTC",
      "updated_at":"2018-03-07 23:34:04 UTC",
      "role_name":"ambassador",
      "properties":{
        "Healthcare Professional":"yes",
      }
    },
    {
      "id":151,
      "status":"Active",
      "ats_id":null,
      "email":"dandre@homenick.net",
      "first_name":"Candy",
      "last_name":"Date",
      "phone":null,
      "recruiter_id":30,
      "recruiter_email":"recruiter@example.com",
      "recruiter_name":"Recruity Recruiter",
      "created_at":"2018-03-07 23:34:02 UTC",
      "updated_at":"2018-03-07 23:34:04 UTC",
      "role_name":"applicant",
      "properties":{
        "Healthcare Professional":"yes",
      }
    },
    {
      "id":148,
      "ats_id":"abc123",
      "status":"Active",
      "email":"brittany@lehnerwest.io",
      "first_name":"Anne",
      "last_name":"Admin",
      "is_accepted":true,
      "phone":null,
      "accept_url":"https://example.staffingreferrals.com/enter/iXRK3YY10I4QyFIyUs89",
      "is_public_recruiter":false,
      "created_at":"2001-02-02 21:05:06 UTC",
      "updated_at":"2018-03-07 23:34:04 UTC",
      "role_name":"admin"
    }
  ]
}

This endpoint retrieves all users in the company, optionally filtered to only get recently updated or created ones. This response will be paginated.

HTTP Request

GET https://example.staffingreferrals.com/api/v1/users

Query Parameters

Parameter	Description
since	An optional ISO-8601 formatted date to provide a lower bound for updates that you are interested in. For example, if you want all referrals created or updated since noon on the Fourth of July in 2017 Denver Time, use `2017-07-04T12:00:00-07:00`.
role_name	An optional string that will filter the users by their role. Can be one of `"ambassador"`, `"applicant"`, `"recruiter"` `"admin"`.
email	An optional string that will search for a user by email. Case insensitive.
ats_id	An optional string that will search for a user by ats_id.
is_accepted	Optionally provide the parameter `is_accepted=true` to filter for only those users that have accepted their invitation and engaged with the system.
page_index	Optional page index. See pagination.
page_size	Optional page size. See pagination.

Response URL Terminology

There are several URLs generated for each user. The following table should clarify how each is to be used.

URL Type	Description
accept_url	This is a private URL that is given to a user for them to accept their invitation. It also allows them access to their account.
join_url	This is a public URL that allows ambassadors to join with a recruiter. A recruiter should share this link to potential ambassadors.
apply_url	This is a public URL that allows applicants to apply with a recruiter. Recruiters and ambassadors should share this link to potential applicants.
is_accepted	An invited user (admin, recruiter, or ambassador) has accepted their invitation by logging into the site at least once.
is_public_recruiter	Whether or not the Recruiters/Admin is configured to show up in dropdowns asking users to select their recruiter.

Get User

require 'curb' # Curl access in ruby

http = Curl.get('https://example.staffingreferrals.com/api/v1/users/USER_ID', {}) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/users/USER_ID" \
  -H "Authorization: YOUR_TOKEN_HERE"

{
  "status":"success",
  "data": {
    "id":149,
    "ats_id":"42",
    "campaign_id":"10",
    "status":"Active",
    "email":"hester_ziemann@metz.name",
    "first_name":"Recruity",
    "last_name":"Recruiter",
    "phone":null,
    "is_accepted":true,
    "campaign_id":10,
    "accept_url":"https://example.staffingreferrals.com/accept/2Gp36qA6zZyR478UItgA",
    "join_url":"https://example.staffingreferrals.com/join/rrecruiter",
    "apply_url":"https://example.staffingreferrals.com/apply/rrecruiter",
    "created_at":"2018-03-07 23:34:02 UTC",
    "updated_at":"2001-02-02 21:05:06 UTC",
    "role_name":"recruiter"
  }
}

This endpoint retrieves a single user in the company, specified by ID.

HTTP Request

GET https://example.staffingreferrals.com/api/v1/users/USER_ID

Query Parameters

Parameter	Description
USER_ID	The Staffing Referrals ID of the user.

Response URL Terminology

There are several URLs generated for each user. The following table should clarify how each is to be used.

URL Type	Description
accept_url	This is a private URL that is given to a user for them to accept their invitation. It also allows them access to their account.
join_url	This is a public URL that allows ambassadors to join with a recruiter. A recruiter should share this link to potential ambassadors.
apply_url	This is a public URL that allows applicants to apply with a recruiter. Recruiters and ambassadors should share this link to potential applicants.

Update User

require 'curb' # Curl access in ruby

http = Curl.post('https://example.staffingreferrals.com/api/v1/users/149',
                 {first_name: "John", last_name: "Doe"}) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/users/149" \
  -H "Authorization: YOUR_TOKEN_HERE" \
  -d "first_name=John&last_name=Doe" \
  -X POST

{
  "status":"success",
  "data":{
    "id":149,
    "ats_id":"42",
    "campaign_id":"10",
    "status":"Active",
    "source":"Your ATS",
    "email":"hester_ziemann@metz.name",
    "first_name":"John",
    "last_name":"Doe",
    "phone":null,
    "is_accepted":true,
    "campaign_id":10,
    "accept_url":"https://example.staffingreferrals.com/accept/2Gp36qA6zZyR478UItgA",
    "join_url":"https://example.staffingreferrals.com/join/rrecruiter",
    "apply_url":"https://example.staffingreferrals.com/apply/rrecruiter",
    "created_at":"2018-03-07 23:34:02 UTC",
    "updated_at":"2001-02-02 21:05:06 UTC",
    "role_name":"recruiter",
  }
}

This endpoint updates a specific user.

HTTP Request

POST https://example.staffingreferrals.com/api/v1/users/USER_ID

URL Parameters

Parameter	Description
USER_ID	The ID of the user
status	One of `"active"`, `"inactive"`
source	Optionally provide the source of the user.
campaign_id	The ID of the new campaign can be determined via the Campaigns endpoint
recruiter_id	The ID of the new recruiter can be determined via the Users endpoint. If you are deactivating a recruiter, please consider using the Deactivate Recruiter endpoint instead of changing users individually.
recruiter_email	The Email of the new recruiter can be determined via the Users endpoint.
fallback_to_default_recruiter	If set to `true` and a recruiter is not found by the `recruiter_id` or `recruiter_email` parameters, and the company uses default recruiter, the user's recruiter will be set to the company default.
first_name	First Name
last_name	Last Name
phone	Phone Number
ats_id	The ID in your ATS

Response

If successful, the API will respond with the details of the user. See example to the right.

Send Access Account Email

require 'curb' # Curl access in ruby

http = Curl.post('https://example.staffingreferrals.com/api/v1/users/send_access_email',
                 {email: 'testing@testing.com'}) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/users/send_access_email" \
  -H "Authorization: YOUR_TOKEN_HERE" \
  -d "email=example@testing.com" \
  -X POST

{
  "status":"success",
  "message":"Sent access acount email to example@testing.com",
}

For sending recovery email to a user who needs access to their account.

HTTP Request

POST https://example.staffingreferrals.com/api/v1/users/send_access_email

URL Parameters

Parameter	Description
email	The email of the user

Response

If successful, the API will respond with a success message.

Deactivate Recruiter

require 'curb' # Curl access in ruby

http = Curl.post('https://example.staffingreferrals.com/api/v1/users/149/deactivate_recruiter',
                 {new_recruiter_id: 42}) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/users/149/deactivate_recruiter" \
  -H "Authorization: YOUR_TOKEN_HERE" \
  -d "new_recruiter_id=42" \
  -X POST

{
  "status":"success",
  "message":"Moved 10 ambassadors and 2 referrals to recruiter 42.",
  "data":{
    "id":149,
    "ats_id":"42",
    "campaign_id":"10",
    "status":"Inactive",
    "email":"hester_ziemann@metz.name",
    "first_name":"John",
    "last_name":"Doe",
    "phone":null,
    "campaign_id":10,
    "accept_url":"https://example.staffingreferrals.com/accept/2Gp36qA6zZyR478UItgA",
    "join_url":"https://example.staffingreferrals.com/join/rrecruiter",
    "apply_url":"https://example.staffingreferrals.com/apply/rrecruiter",
    "created_at":"2018-03-07 23:34:02 UTC",
    "updated_at":"2001-02-02 21:05:06 UTC",
    "role_name":"recruiter",
  }
}

This endpoint deactivates a recruiter or admin. It requires that you pass an ID for a new recruiter to which all of the recruiter's ambassadors and leads will be moved.

Ambassadors which are in an invitation email flow will continue in the flow, but all subsequent emails will be sent from their new recruiter.

HTTP Request

POST https://example.staffingreferrals.com/api/v1/users/USER_ID/deactivate_recruiter

URL Parameters

Parameter	Description
USER_ID	The ID of the admin or recruiter to deactivate
new_recruiter_id	The recruiter which is inheriting the deactivating recruiter's ambassadors and leads.

Response

If successful, the API will respond with the details of the user. See example to the right.

Invites

Send Invitation

require 'curb' # Curl access in ruby

http = Curl.post('https://example.staffingreferrals.com/api/v1/invite/invite',
                 { role: 'ambassador',
                   user: {
                     email: 'ambassador@email.com',
                     first_name: 'Anne',
                     last_name: 'Ambassador',
                     phone: '505-555-5555',
                     recruiter_id: 1234,
                     send_at: '2017-07-04T12:00:00-07:00'
                   }
                 }) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/invite/invite" \
  -H "Authorization: YOUR_TOKEN_HERE" \
  -d "role=ambassador&user[email]=ambassador@email.com&user[first_name]=Anne&user[last_name]=Ambassador&user[phone]=505-555-5555&user[recruiter_id]=1234&send_at=2017-07-04T12:00:00-07:00" \
  -X POST

{
  "status":"success",
  "data": {
    "id": 51127,
    "status": "Active",
    "source": "Your ATS",
    "email": "an-ambassador@gmail.com",
    "first_name": "James",
    "last_name": "Dean",
    "phone": null,
    "ats_id": null,
    "apply_url": "https://example.staffingreferrals.com/apply/jdean",
    "accept_url": "https://example.staffingreferrals.com/enter/BCJ6K86YSCfkuvvQuI",
    "recruiter_id": 51116,
    "recruiter_email": "recruiter@example.com",
    "recruiter_name": "Example Recruiter",
    "join_url": "https://example.staffingreferrals.com/join/jdean",
    "created_at": "2019-02-21 16:31:59 UTC",
    "updated_at": "2019-02-21 16:31:59 UTC",
    "role_name": "ambassador"
  }
}

This endpoint allows you to invite ambassadors and applicants to your referral program.

HTTP Request

POST https://example.staffingreferrals.com/api/v1/invite/invite

URL Parameters

Parameter	Required	Description
role		One of `"ambassador"`, `"applicant"`, `"recruiter"`. Defaults to ambassador.
user[email]	Required	The email of the ambassador you want to invite. If this is provided for an existing ambassador, it will be ignored.
user[first_name]	Required	The first name of the user.
user[last_name]		The last name of the user.
user[phone]		The phone number of the user.
user[campaign_id]		The ID of the campaign for the recruiter, if the company default is not to be used.
user[recruiter_id]		The ID of the recruiter who the invite will be sent from. Do not provide when inviting a recruiter.
user[recruiter_email]		The email of the recruiter who the invite will be sent from. Do not provide when inviting a recruiter.
user[is_squelch_email]	Optional	Set to true to create, but without sending email invitations to user.
user[source]	Optional	The source of the user.
send_at	Optional	An optional ISO-8601 formatted date to specify when ambassador email flow will start. Currently, TextUs SMS follow ups do not work for invites delayed with a send_at parameter.

Response

If successful, the API will respond with the details of the invited user. See example to the right.

Campaigns

Get All Campaigns

require 'curb' # Curl access in ruby

http = Curl.get('https://example.staffingreferrals.com/api/v1/campaigns', {}) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/campaigns" \
  -H "Authorization: YOUR_TOKEN_HERE"

{
  "status":"success",
  "data":[
    {
      "id":48,
      "name":"Sandbox Campaign",
      "status":"Live",
      "minimum_term":2,
      "minimum_term_units":"weeks",
      "applicant_bonus":"$500",
      "ambassador_bonus":"$42",
      "is_bonus_per_hour":false,
      "location":"L.A.",
      "minimum_requirements":"Must be an RN in California"
    }
  ]
}

This endpoint retrieves all campaigns in the company.

HTTP Request

GET https://example.staffingreferrals.com/api/v1/campaigns

Property Types

Get All Property Types

  
    require
    'curb'
    # Curl access in ruby

    http = Curl.get('https://example.staffingreferrals.com/api/v1/property_types', {}) do |http|
    http.headers['Authorization'] = "YOUR_TOKEN_HERE"
    end

    json = JSON.parse(http.body)

  curl "https://example.staffingreferrals.com/api/v1/property_types" \
  -H "Authorization: YOUR_TOKEN_HERE"

  
    {
      "status":"success",
      "data":[
        {
          "type":"Text",
          "id":56,
          "name":"Job Title",
          "is_required":true,
          "is_for_ambassador":false,
          "is_for_applicant":true,
          "placeholder":"e.g. Nurse, Doctor, etc."
        },
        {
          "type":"Yesno",
          "id":57,
          "name":"Professional",
          "is_for_ambassador":true,
          "is_for_applicant":true
        },
        {
          "type":"Select",
          "id":58,
          "name":"Years Experience",
          "is_required":true,
          "is_for_ambassador":true,
          "is_for_applicant":true,
          "options":["One","Two","Three"]
        }
      ]
    }

This endpoint retrieves all configured Property Types for the company. These can be configured via the Staffing Referrals website by an admin in the Settings > Custom Properties page.

HTTP Request

GET https://example.staffingreferrals.com/api/v1/property_types

Update Property Type

require 'curb' # Curl access in ruby

http = Curl.post('https://example.staffingreferrals.com/api/v1/property_type/58',
                 {options: ["One", "Two"].as_json.to_s}) do |http|
  http.headers['Authorization'] = "YOUR_TOKEN_HERE"
end

json = JSON.parse(http.body)

curl "https://example.staffingreferrals.com/api/v1/property_types/58" \
  -H "Authorization: YOUR_TOKEN_HERE" \
  -d "options=[\"One\",\"Two\"]" \
  -X POST

{
  "status":"success",
  "data":{
    "type":"Select",
    "id":58,
    "name":"Years Experience",
    "is_required":true,
    "is_for_ambassador":true,
    "is_for_applicant":true,
    "options":["One","Two"]
  }
}

This endpoint updates a specific property type. You cannot change the type via API, but all other fields for a type can be updated.

HTTP Request

POST https://example.staffingreferrals.com/api/v1/property_types/PROPERTY_TYPE_ID

URL Parameters

Parameter	Types	Description
PROPERTY_TYPE_ID		The ID of the property type
name	All	The name of the property
is_required	All	Boolean for whether or not the user will be required to provide the field value.
is_for_ambassador	All	Will this field show up for ambassadors joining the program? If it's also required, ambassador unique links will force them to provide the parameter the first time they visit the site.
is_for_applicant	All	Will this field show up for applicants joining the program?
placeholder	Text	The placeholder text to prompt a user for a text field.
options	Select	The JSON formatted array of options to present a user in the dropdown.

Response

If successful, the API will respond with the updated details of the property type. See example to the right.