Jobport API (1)

The Jobport API provides a robust and flexible interface for managing your data in Jobport.

The Jobport API is mostly RESTful and adheres to the JSON:API specification for consistency and interoperability.

A variety of JSON:API libraries are available for most programming languages to help you interact with the API. The list of JSON API implementations is a good starting point.

Use this base URL for all requests unless instructed otherwise:

https://api.services.jobport.nl/public/v1/

Set the following HTTP headers with every request.

For more information on the Authorization header, see the Authentication section.

When POSTing or PATCHing data, also include the Content-Type header.

Example

  curl -X POST "https://api.services.jobport.nl/public/v1/..." \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json"

Your application may be authorized to make changes for multiple organizations. Therefore most paths are prefixed with /organizations/{organization_id}/, e.g. /organizations/{organization_id}/dossiers. When retrieving resources this will only return the resources associated with a particular organization. When creating a resource it will associate the resource with the organization.

The same applies to other nested paths, such as /organizations/{organization_id}/dossiers/{dossier_id}/user_contexts.

Endpoints that list resources may support filtering using the filter[] query parameter. This parameter accepts a list of filter values, where each value typically consists of a filter name and a value separated by a colon. Flags use only the filter name. For example: ?filter[]=active&filter[]=name:paul. Many filters may be included multiple times to filter on multiple values, e.g. ?filter[]=name:paul&filter[]=name:john.

Sparse fieldsets allow you to specify which fields you want to include in the response. Use the fields query parameter to specify a comma-separated list of fields for each resource type. For example: ?fields[dossiers]=id,name,created_at.

Note that for export endpoints this works slightly differently: the fields must be specified without the resource type prefix. For example: ?fields=id,name,created_at. Exports never include other resource types other than the one being exported.

Endpoints that list resources may support sorting using the sort query parameter. This parameter accepts a comma-separated list of field names to sort by. Prefix a field name with a minus sign (-) to sort in descending order. For example: ?sort=name,-created_at.

Available sorting options vary by endpoint and are documented in each endpoint’s documentation.

When retrieving a list of resources, the response will include a top level meta object containing additional information about the response, such as pagination details (page, page_size).

Endpoints that list resources support optional inclusion of the total count of resources in the meta object. Use the _count query parameter to do so. For example: ?_count=true. The meta object will include a total field indicating the total number of resources available, regardless of any filters applied.

Note that export endpoints do not return a meta object, as they are designed to export all available data without pagination.

Jobport allows a single user to have access to multiple contexts across different organizations. For example, a person can be a coach for organization 'A' and 'B', and also be a client coached by organization 'C'. This user would have three user contexts. If a user has multiple contexts, they can switch between them without logging out and back in.

Storing user contexts

A user context ID is permanent and reused even after deactivation and reactivation. If your app stores these IDs (e.g. for SSO), note that inactive contexts may return a 404 when accessed.

If you encounter issues with the API, or want to suggest improvements, please let us know at https://www.jobport.nl/contact.

Your application must send a self-generated short-lived JSON Web Token (JWT) with each request you send to the API. This token identifies your application with a digital signature.

To create signed JWTs, you will receive from us:

• A unique ID to identify your application (referred to as the app_id)
• A shared secret to sign the JWTs (keep this confidential)

To request these credentials for your application, contact us at https://www.jobport.nl/contact. API access is available for selected customers only. Please provide the name of your application and describe the purpose of the integration you are building. We will then review your request. When eligible we will create an application for you with the appropriate permissions and provide you with the necessary credentials.

A signed JWT has three parts: a header, a payload, and a signature. Do not base64-encode the secret when generating the token. You can reuse a token until it expires or generate a new one for each request. The latter might be simpler to manage and could increase security by limiting the token's lifetime (see exp below).

The header must contain:

The payload must contain:

Most programming languages have libraries available to help you create signed JWTs. Basically, it takes three steps:

1. token = base64UrlEncode(header) + "." + base64UrlEncode(payload)
2. signature = HMACSHA256(token, shared_secret)
3. signed_token = token + "." + signature

You can use https://jwt.io to check if your JWTs are valid and contain the correct data. Never enter your shared secret into third party tools. If you need to do that, please request another shared secret for production use once you have authentication set up.

Example

# Assume we want our example JWT to contain the following header and payload:
header = { "alg": "HS256", "typ": "JWT" }
payload = { "app_id": "673943a3-8df4-421d-ad5b-34e747cadd83", "exp": 1505487093 }

# We then encode and combine the parts:
token = base64UrlEncode(header) + "." + base64UrlEncode(payload) # => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI2NzM5NDNhMy04ZGY0LTQyMWQtYWQ1Yi0zNGU3NDdjYWRkODMiLCJleHAiOjE1MDU0ODcwOTN9

# Then calculate the signature:
shared_secret = `your-256-bit-secret`
signature = HMACSHA256(token, shared_secret) # => SSqSQeVlLjqdrm5cPqTcXLwaq_w7UJmsWJZ8oDCPJ_g

# Finally, append the signature to get your signed JWT:
signed_token = token + "." + signature # => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiI2NzM5NDNhMy04ZGY0LTQyMWQtYWQ1Yi0zNGU3NDdjYWRkODMiLCJleHAiOjE1MDU0ODcwOTN9.SSqSQeVlLjqdrm5cPqTcXLwaq_w7UJmsWJZ8oDCPJ_g

If you’re unable to generate a JWT dynamically, we can provide a static, long-lived token for authenticating your requests. However, we strongly recommend using short-lived JWTs for better security. To request a static token, contact us. Keep static tokens confidential. They must be renewed annually.

Set the Authorization header with the value Bearer {signed_token} in every request you make to the API.

Example

curl "https://api.services.jobport.nl/..." \
  -H "Authorization: Bearer $SIGNED_TOKEN"

Use the token exchange endpoint when your application needs to perform actions on behalf of a user.

Use the one-time SSO URL endpoint to create a short-lived SSO URL that your user can use to log in to Jobport.

Endpoints for retrieving user tokens.

Jobport supports SSO with secure, one-time URLs for one specific user context. The URL can be used only once and expires within seconds after creation. Request the SSO URL just before the user needs to log in, then redirect them immediately.

A user may belong to multiple organizations. After logging in with an SSO URL, the user will only have access to the organization for which the SSO URL was generated. This prevents unauthorized access to other organizations.

Endopoints for retrieving user contexts.

Endpoints for retrieving conversations.

Endpoints for managing dossiers. Dossiers hold information about a candidate. Once a dossier exists you can (optionally) invite the candidate to create a Jobport account.

Endpoints for retrieving employers.

Endpoints for retrieving notifications.

Endpoints for managing employer vacancies.

Endpoints for retrieving saved vacancies.