logo
API docs by Redocly

Sourceflow API (1.0.0)

Download OpenAPI specification:

This documentation details the API for the Sourceflow platform.

Where endpoints require authentication, it will be marked as OAuth2.0. Authentication uses the client credentials flow of OAuth 2.0. See https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow for more information.

The token endpoint is /_sf/api/oauth/token.json. Authenticated endpoints require an Authorization header with the value Bearer TOKEN, where TOKEN is a UUID valid for 1 hour.

Authentication

Obtain OAuth2 access tokens using the client credentials flow

Get access token

Obtain a Bearer token using the OAuth 2.0 client credentials flow. The returned token is valid for 1 hour and must be included in subsequent authenticated requests as Authorization: Bearer TOKEN.

Request Body schema: application/json
required
grant_type
required
string
Value: "client_credentials"
client_id
required
string

Your OAuth2 client ID

client_secret
required
string

Your OAuth2 client secret

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials",
  • "client_id": "your-client-id",
  • "client_secret": "your-client-secret"
}

Response samples

Content type
application/json
{
  • "access_token": "5b83dc8e-b95b-4c68-9e94-368a63e4b4f3",
  • "token_type": "bearer",
  • "expires_in": 3599
}

Jobs

Create, update, and delete job postings

Create a new job

Create a new job posting. external_reference and url_slug must be unique.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
object (JobInput)

Responses

Request samples

Content type
application/json
{
  • "job": {
    }
}

Response samples

Content type
application/json
{
  • "action": "create",
  • "status": 0,
  • "job": {
    }
}

Update or create a job (by external_reference)

If a job with the given external_reference exists it will be updated; otherwise a new job will be created. Returns an action field indicating whether the record was created or updated.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
object (JobInput)

Responses

Request samples

Content type
application/json
{
  • "job": {
    }
}

Response samples

Content type
application/json
{
  • "action": "create",
  • "status": 0,
  • "job": {
    }
}

Update or create a job using simplified category names

Same upsert behaviour as /jobs/update_or_create.json but accepts human-readable category names (e.g. sector names) instead of UUIDs. Use /jobs/simplified_categories.json to retrieve the available names.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
object (SimplifiedJobInput)

Simplified job creation/update using category names instead of UUIDs

Responses

Request samples

Content type
application/json
{
  • "job": {
    }
}

Response samples

Content type
application/json
{
  • "action": "create",
  • "status": 0,
  • "job": {
    }
}

Update an existing job

Partially update an existing job. Only fields included in the payload will be changed. Setting a field to null will clear its value.

The {jobId} can be either the external_reference used when creating the job, or the Sourceflow UUID returned on creation.

Authorizations:
oauth2ClientCredentials
path Parameters
jobId
required
string

Sourceflow UUID or external_reference of the job

Request Body schema: application/json
required
object (JobInput)

Responses

Request samples

Content type
application/json
{
  • "job": {
    }
}

Response samples

Content type
application/json
{
  • "action": "create",
  • "status": 0,
  • "job": {
    }
}

Delete a job

Permanently delete a job from the website and search index. This cannot be undone and will remove the job's web page (potentially breaking existing links).

If you only want to hide a job, use PATCH to set expires_at to a date in the past.

The {jobId} can be either the external_reference or the Sourceflow UUID.

Authorizations:
oauth2ClientCredentials
path Parameters
jobId
required
string

Sourceflow UUID or external_reference of the job

Responses

Retrieve all live job references

Returns an array of external_reference strings for all currently live jobs.

Authorizations:
oauth2ClientCredentials

Responses

Response samples

Content type
application/json
[
  • "JOB-12345",
  • "JOB-67890"
]

Get similar jobs

Returns jobs similar to a specified job, based on category matching.

query Parameters
job_id
required
string

The external_reference or Sourceflow UUID of the source job

Responses

Response samples

Content type
application/json
{
  • "jobs": [
    ]
}

Search for jobs

Search and filter the job index. Supports text queries, category filters, and commute-time filtering. Pagination is supported via page_token.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "job_search": {
    }
}

Response samples

Content type
application/json
{
  • "jobs": [
    ],
  • "page_token": "string"
}

Job Categories

Retrieve job category definitions and their available values

Get all available categories

Returns all job categories with their metadata.

Authorizations:
oauth2ClientCredentials

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all simplified categories

Returns all categories in a simplified format designed for use with the /jobs/update_or_create_simplified.json endpoint. Keys match the field names accepted by that endpoint.

Authorizations:
oauth2ClientCredentials

Responses

Response samples

Content type
application/json
{
  • "sectors": [
    ],
  • "employment_types": [
    ],
  • "salary_bands": [
    ],
  • "consultants": [
    ],
  • "regions": [
    ],
  • "pay_period": [
    ],
  • "hybrid_working": [
    ]
}

Get values for an individual category

Returns detailed information for a single category including all of its values.

Authorizations:
oauth2ClientCredentials
path Parameters
categoryId
required
string <uuid>

UUID of the category

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "identifier": "string",
  • "category_values": [
    ]
}

CMS

Manage CMS content categories and their schemas

Get all CMS categories

Returns all CMS categories.

Authorizations:
oauth2ClientCredentials

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a CMS category

Creates a new CMS category with a defined schema.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
dataset_id
string <uuid>
name
required
string
description
string
required
Array of objects (CmsCategorySchemaField)
has_template
boolean
url_pattern
string
identifier
required
string
job_categorisation
boolean
is_job_categorisation_required
boolean
is_nested
boolean
default_sort_field
string
default_sort_direction
string
Enum: "ASC" "DESC"
simplified_api_name
string
category_type
Array of strings
locked_values
boolean

Responses

Request samples

Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "name": "string",
  • "description": "string",
  • "schema": [
    ],
  • "has_template": true,
  • "url_pattern": "string",
  • "identifier": "string",
  • "job_categorisation": true,
  • "is_job_categorisation_required": true,
  • "is_nested": true,
  • "default_sort_field": "string",
  • "default_sort_direction": "ASC",
  • "simplified_api_name": "string",
  • "category_type": [
    ],
  • "locked_values": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "identifier": "string",
  • "category_values": [
    ]
}

Get a single CMS category

Returns a specific CMS category by ID, including its schema and all values.

Authorizations:
oauth2ClientCredentials
path Parameters
categoryId
required
string <uuid>

UUID of the CMS category

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "identifier": "string",
  • "category_values": [
    ]
}

Placements

Submit and manage placement data for analysis and reporting

Get all placements

Returns all placement records.

Authorizations:
oauth2ClientCredentials

Responses

Response samples

Content type
application/json
[
  • { }
]

Update or create a placement

Placement is located by external_placement_id. If found it will be updated; otherwise a new placement record is created.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
object (PlacementInput)

Responses

Request samples

Content type
application/json
{
  • "placement": {
    }
}

Delete a placement

Deletes a placement identified by the external_placement_id query parameter.

Authorizations:
oauth2ClientCredentials
query Parameters
external_placement_id
required
string

External placement ID to delete

Responses

Emails

Send emails via the Sourceflow platform

Send an email

Sends an email via the Sourceflow platform.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
to
required
string <email>
subject
required
string
body
required
string

Responses

Request samples

Content type
application/json
{
  • "to": "recipient@example.com",
  • "subject": "Hello from Sourceflow",
  • "body": "hello\n cruel\n world"
}

API Users

Provision and manage API partner users

Provision an API user

Provisions a new API partner user, returning client credentials.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "api_user": {
    }
}

Response samples

Content type
application/json
{
  • "message": "API User 'Partner Name API User' provisioned.",
  • "user": {
    }
}