Introduction

Version: 25.3.7.3
Last updated: see description below
Terms of Service: https://www.precisionpartner.nl/terms-of-service
Support: support@precisionpartner.nl

Last updated date: 2025-10-10

Meridian by Precision Partner API allows using HTTP requests to access the environment's data and control the application without opening its graphical interface. This allows you to return information or manipulate the data according to your business needs.

Meridian Data Model Concept

In Meridian, the data structure is segregated into 5 data models (Endpoints):

• Company: Company basic information consists of Company Name, Locations, Note, Documents etc.

• Contact: Contact consists of the client's contact basic information. It includes contact name, job title, company name, phones, emails, activities, documents etc.

• Job: Job consists of job title, job description, job notes, job types etc.

• Candidate: Candidate consists of various candidate information which includes, candidate basic information, work history, activities, resume etc.

• Job Application: This is the candidate's job application that links the candidate with the job. It consists of the application stages (Shortlisted to Placed), status and sub status of the application.

URLs

All APIv2 access is over HTTPS. HTTP requests will be redirected to HTTPS. The APIv2 should be accessed using a Meridian account specific domain https://<yourdomain>.precisionpartner.nl/api/v2/

Content-Type Data In / Out

The Meridian API accepts and returns data in specific CONTENT-TYPE. This format type must be specified in the HTTP Body.

HTTP Method	Content-Type Data In	Content-Type Data Out	Remarks
GET	ANY TYPE	JSON	Retrieves a resource representation without modifying it.
POST	JSON	JSON	Creates a resource and used to search for a criteria
PUT	JSON	JSON	Updates a resource that requires all payload to be existing.
PATCH	JSON	JSON	Makes a partial update on a resource. Does not replace the entire resource.
DELETE	ANY TYPE	JSON	Removes an entire resource.

API Authentication Flow

Before you can make a call to the Meridian APIv2, your request must be authenticated using Meridian's OAuth2 flow with an authorization code grant process. If you are new to OAuth2, you can read the following introduction.

API Terms Glossary

Identity Service: Meridian service hosted at https://id.precisionpartner.nl responsible for accepting OAuth2 requests to authorize Meridian users.

Meridian User: Any user that has login credentials to the target Meridian account. A Meridian admin user is a user with the administrator role.

Application Developer: You as a third-party or Meridian user who would like to make API requests to a Meridian account on behalf of a Meridian user.

Client App: Application the application developer is building that requires access to a Meridian account using this API.

Api Key: Required key that must be included with all API requests to a Meridian account. API keys can be requested from an admin user of the Meridian account.

Client Id: Unique identifier that identifies your third-party application or Meridian account attempting to request authorization credentials on behalf of a Meridian user. Client ids can be requested from an admin user of the Meridian account.

Callback URL: URL provided by the third-party application that will receive the authorization code for authorization requests. It must be configured by an admin user of the Meridian account before making OAuth2 authorization requests.

Authorization Code: Special code that is valid for 3-minutes and forwarded to the registered callback url after a Meridian user successfully logs in and authorizes the third-party application to make API requests on their behalf. It must be sent to the identity service to swap for an id token and refresh token.

Id Token: Token required in all API requests that grants identification and access to the Meridian account API resources. It is generated by sending a grant request to the identity service that contains either a valid authorization code or a valid refresh token.

Refresh Token: Special token used instead of the authorization code to perpetually generate new id tokens by sending to the identity service. It is valid for 10 years or until manually revoked by Meridian. It must be kept securely on the third-party application's backend servers. For instance it should never be stored in a client device or browser session.

How to Use - Meridian API "Try It" Feature

Prerequisite Setup

As the Application Developer or a Meridian Admin User, you must have your environment's credentials ready for the following steps below. If not, please contact our Meridian Support Team for assistance.

Setup

1. Head over to the API Server tab and add your environment's sub-domain under the Server Variable's tenant field.

Example:

Placeholder API Server: https://{tenant}.precisionpartner.nl/api/v2
After adding a sub-domain: https://Meridian-rec.precisionpartner.nl/api/v2

2. Navigate to the Authentication tab and set your client_id and click on GET TOKEN to Authenticate.
3. When you have entered the correct credentials to authentication, add your api-key and click SET.
4. Once you've done the steps above, you are now able to try calling the API by fullfilling the resource's required fields.

How to Use - Meridian API Manual Authentication Process

Prerequisite Setup

As the Application Developer or a Meridian Admin User, you must give your redirect_uri (callback url) to the Meridian support team. Meridian credentials, inclusive of Client ID and API Key, are created by Meridian.

Generate ID Token

Use the cURL below and replace the following parameters based on your environment's credentials

curl --location 'https://id.precisionpartner.nl/oauth2/authorize?client_id=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx&state=STATE&redirect_uri=https://your_callback_url&response_type=code' \
--header 'Content-Type: application/x-www-form-urlencoded'

Parameter	Value	Remarks
response_type	string	This must be the code
client_id	string	This is the client id provided by Meridian Support
redirect_uri	string	This is the callback url you provide
state	string	Any urlencoded string to pass along to the callback url to track state within the client app

Authentication

A login page will be displayed which will then require your Meridian User account. Upon successful login, will be forwarded to your callback url with the following signature:

https://(callback url)?code=(authorization code)&state=STATE

Authorization

Once the code is retrieved, an authorization is required to fetch an id-token

curl --location --request POST 'https://id.precisionpartner.nl/oauth2/token' -d 'client_id=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx&grant_type=authorization_code&code=xxxxxxx' \
--header 'Content-Type: application/x-www-form-urlencoded'

Header	Value
Content-Type	application/x-www-form-urlencoded

Body	Value	Remarks
client_id	string	This is the client id provided by Meridian Support
code	string	This is the callback url you provide
grant_type	string	The value must be set as authorization_code

Response	Value	Remarks
access_token	string	This token type is not used with the Meridian API Authentication flow.
refresh_token	string	Token required to subsequently acquire new id token values. This must be stored securely in a backend service and never on a client device or browser.
id token	string	A short lived token that identifies and grants access to the Meridian API on behalf of the Meridian user that authorized the client app. It expires in 1 hour and must be refreshed with the refresh token to continue accessing.
token_type	string	This type will be always set as Bearer
expires_in	integer	The number of seconds the id token is valid for.

Refresh ID Token

When your id token has expired. You can send a grant_type=refresh_token request similar to the code flow above to get a new id token.

curl --location --request POST 'https://id.precisionpartner.nl/oauth2/token' -d 'client_id=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx&grant_type=refresh_token&code=xxxxxxx&refresh_token=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx' \
--header 'Content-Type: application/x-www-form-urlencoded'

Header	Value
Content-Type	application/x-www-form-urlencoded

Body	Value	Remarks
client_id	string	This is the client id provided by Meridian Support
refresh_token	string	The refresh token saved from the code flow above.
grant_type	string	This must be the refresh_token
code	string	This is the callback url you provide

Response	Value	Remarks
access_token	string	This token type is not used with the Meridian API Authentication flow.
id token	string	A short lived token that identifies and grants access to the Meridian API on behalf of the Meridian user that authorized the client app. It expires in 1 hour and must be refreshed with the refresh token to continue accessing.
token_type	string	This type will be always set as Bearer.
expires_in	integer	The number of seconds the id token is valid for.

Calling the Meridian APIv2

After you have acquired an authorized and valid id token, you can make API requests to the Meridian account on behalf of the Meridian user that made the authorization.

Example - GET: Candidate Details

curl --location 'https://zenith.precisionpartner.nl/api/v2/candidate/' \
--header 'id-token: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx' \
--header 'x-api-key: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx' \
--data ''

Headers	Value	Remarks
id-token	string	A short lived token that identifies and grants access to the Meridian API on behalf of the Meridian user that authorized the client app. It expires in 1 hour and must be refreshed with the refresh token to continue accessing.
x-api-key	string	This is the API key provided by Meridian Support
content-type	string	This should always be application/json (not usually required for GET & DELETE requesets)

Important Note:

• We advise you to be extremely cautious when sharing your api key and client id internally & externally to ensure that your data is safe.
• You will be responsible on how you handle this token sharing. Any security incidents caused by unmanaged token sharing which is performed outside of Meridian's control will be your responsibility and not Meridian.
• Expired or unauthenticated requests will return an HTTP 401 response.

Throttling (Rate-Limits)

Calls to the APIv2 are throttled to ensure that your API request does not consume excessive resources. The limits should only affect scripts that are malfunctioning, or attempting to make too many requests in parallel.

In Meridian, the limit is set to 10 requests per second and 50,000 requests per day per api key. If more than 10 requests are made in a one second period or more than 50,000 requests are made in one day then subsequent requests will fail with a 429 response. The rate limit is applied per api key so any requests sent with the same api key will contribute to the limit.

Important Note:

• Our request rate limit is 10 requests per second and the quota is set at 50,000 requests per day

Please contact us in case you need to change the above limits.

Pagination

All API v2 methods that return a collection of results may be paginated. The results from such API calls will include the following information.

Response	Value	Remarks
slice_index	integer	The index of the current slice.
num_of_elements	integer	The number of elements in the current slice.
last	boolean	The boolean value which indicates if there is more slices after this slice.
content	content	The array of elements returned in this slice.

Error handling

This part of the document will describe the most frequent error codes returned by the Meridian API. If your request is incorrect, in the response, you can find the details of the error that should help you to troubleshoot. All Meridian API errors have the same schema. Below you can see the example of a response for the request with the incorrect parameter.

Status	Response	Explanation
400	Bad Request	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401	Unauthorized	This response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
403	Forbidden	You do not have access rights to the resource which means that your request was unauthorized. Commonly caused by an api-key that does not correspond to its client-id.
404	Resource Not Found	The server cannot find the requested resource (probably it does not exist) even if the endpoint is valid.
413	Payload Too Large	Request entity is larger than limits defined by server.
424	Failed Dependency	The request failed due to failure of a previous request.
429	Too Many requests	You have exceeded the rate limit of API requests for your api-key. Wait for one minute for the limit period to reset.
500	Internal Server Error	The server has encountered a situation it does not know how to handle.

Important Note:

• For the error codes 401, 403, 413 and 429, the response body may contain the message of the error.
• For error code 400, 404, 405, 424 and 500, the response body may contain the following parts:

Example Error: "Data is invalid"

{"status": "FAILED"
"httpStatus": "404"
"errorId": **This value is unique for each error**, for example, "e96297f1-304a-4dd1-8bd8-18c3fcc2e877"
"errorCode": May be optional, available if it is a business violation (as opposed to a technical violation).
"errors": An array of plain strings to explain the errors
}

Date and Time

Across all the API, when a resource involves a date (with or without time) value, we only supported the UTC format.

"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"

Important Note:

• For our time part, HH:mm:ss.SSS, this format may be ignored by some API's. Please check the documentation of the external APIs ascertain if their time format conflicts with the Meridian API v2.

Geo-coding

Our API will often require you to specify geographic locations.

Location objects can consist of six parts: address, city, country_code, district, latitude, location_name, longitude, nearest_train_station, post_code, state. Not all of these values are mandatory.

Each Candidate, Contact, Company has its own location while a Job's working location references only one of the Company's locations. Please refer to Location object for details.

https://api.precisionpartner.nl/documentation.html#section/Geo-coding

Search

The Meridian Search API V2 uses a SOLR backend framework for our search API. To help developers with their queries, we have defined a custom query parser to simplify the work required by transforming queries using the SOLR search engine.

There are FOUR endpoints you can run a search on: Candidates, Contacts, Jobs & Companies. At the most basic level, you can perform your search using four elements: Range, Text, Radius & Value. This will do a simple filter on a field based on a value. What fields can be filtered on and what filters can be used on each filter are described on each of the endpoints themselves.

Beyond the four search types, we also offer the ability to chain filters together using Boolean operators such as AND, OR, and NOT. Meridian search also supports customizable sorting plus more like this operators and provides a way to offer language-specific searches for different languages.

A basic Meridian Query would be structured as follows:

field: terms # OPERATOR fields: terms #

For Example:

industryid: 1 AND 2 AND 3 AND 4 # AND text: "Senior" "Junior" "Developer" Anna # OR feid: NOT (1) #

A more detailed explanation is as follows:

1. #: letter to ending terms - mandatory. It's needed to help regcognize the end of current expression, and start parsing new expressions.
2. industryid OR text: search fields
3. 1 AND 2 AND 3 AND 4: search term.

Based on your fields + the field type, you will need to construct the correct search terms.

Below is explaination on search types:

• TEXT
  • Text search. You can use multiple terms with operators.
    If your terms contains quotes, you are searching EXACTLY. Terms without quotes would be treated as CONTAINS.
  • Example: text: A "B" AND (B OR C) #
• VALUE
  • Same as TEXT type, but you need to use value_search defined in reference section.
  • Example: industryid: A AND (B OR C) #
• RANGE
  • Range search. Used for salary range or datetime type. For date_time type, the parser supports only 2 formats: yyyy-MM-dd and yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. Static value: ALL & NOW
  • Example: salary_from: {1 TO 100] # AND created_date: {2017-12-20 TO ALL] #
• RADIUS
  • Radius search used for searching location
  • Example: location_radius:d=5,unit=km,lat=30.5587915,lng=-96.24604569999997 #

To use MoreLikeThis search feature you need more effort. Firstly you needs to construct a query to identify which record for finding similarity, then add more filter queries to filter out your search result.

For example: query below would find similar not - closed - and - public jobs that have to match at least one functional experties OR industry with the job ID 32813 (you need to escapse your query)

/api/v2/job/search/fl=id,job_title,private_job,closed_date,published_date,fe,industry;mlt.fl=private_job,industry_id,fe_id;sort=published_date desc?fq=private_job:0 #&fq=closed_date:{NOW TO ALL] #&q=id:32813 #&language=en&start=0&limit=100

As described above, # is special keyword of Meridian Search APIs. In case your search terms contains #, your responsibility is to escape the special keywords in your search terms as followings, and # can only be searched when it is part of a standard dictionary word (for example C#).

Keyword	Escaped character
#	.08

As of 12.11.0, start param is limited to 10000. If you need deep paging, Meridian search supports cursorMask param. cursorMask param, at begining query, you need to pass in wildcard (*). The returned result with cursorMask param would include cursorMask for next page. You need to loop your query with cursorMask until the new cursorMask duplicated with some previous one.

Example of cursorMask usage:

GET /api/v2/candidate/search/fl=id,first_name, first_name_kana, created_date,photo,current_location;sort=created_date asc?cursorMark=QW9KK3BwV0d0ZXNDUHdsc2IyTmhiR2h2YzNRdWRtbHVZMlZ5WldSbGRpNWpiMjBoWTJGdVpHbGtZWFJsWHpNMk5qTTU=

Versioning

The Meridian API v2 requires a version to be specified in every request URL. The Version needs to be placed immediately after our base URL: https://api.precisionpartner.nl/api/v2/.

An example URL accessing offer with id 511394 using API version 2 will be: https://api.precisionpartner.nl/api/v2/offers/51139

Servers

• https://{tenant}.precisionpartner.nl/api/v2 — Your tenant API server.
  • {tenant}: default testprod — Your tenant sub domain.

Endpoint Groups

• activity — Activities consist of Comments, Tasks, Meetings and Emails.
  End of the activities is linked to Candidates, Contacts, Jobs and Companies.
• application — Applications, otherwise known as Job submissions, Job status, Job objects or Job actions.
  Applications associate Candidates with Jobs. Candidate applications always have exactly 1 job.
• candidate — Candidates, otherwise known as applicants.
  A Candidate can be linked to a contact in Meridian.
  The candidate entity is the only entity that can be floated to contacts, apply for or be shortlisted and / or sent to open jobs.
• company — Companies, otherwise known as Corporations or Client corporations are entities that Contacts work at.
  These Companies can be used as Prospect or Lead Companies, Headhunt sites, or as Clients.
• contact — Contact Endpoints.
  Contacts, otherwise known as Clients or Client Contacts are persons working at Companies.
  They can be used as Prospects, Leads, Headhunt lists , Employees or Clients.
  A Contact cannot exist in Meridian without being linked to a Company.
  Contacts are separate entities to Candidates, but they can be linked together.
  Jobs must link to a Contact in Meridian.
• distribution list — Distribution list of contacts.
• email subscription — Email Subscription
• file — Files consist of documents and photos. Meridian accepts the following files types:
  For document: doc, docx, pdf, rtf, xls, xlsx, html, msg
  For photo: png, jpg, gif, bmp
  Note on Documents: Maximum allowable document file size is 10 MB.
  Note on Photos: Maximum allowable photo image size is 800 KB
  Important: At present, the API v2 only supports Documents for Candidates.
  For Companies, Contacts and Jobs we only support the GET call for logo/photo.
  In the coming months, we will add the Document API's for Companies, Contacts and Jobs.
• invoice — Invoices
• job — Jobs, otherwise known as Positions, Vacancies or Job orders are entities that linked to Contacts that are in turn linked to Companies.
  A Job cannot be added to Meridian without being associated to a contact.
  For avoidance of doubt, Jobs do NOT directly link to Companies.
• placement — Placements
• report — Calls to obtain statistics in Meridian.
• reference — These are calls to obtain reference (read-only) objects.
  Note that Meridian would cache API calls to these endpoints for 3 hours.
  As a result, sometimes your newest updates would not be reflected in reference API calls.
• search — The Meridian Search API V2 uses a SOLR backend framework for our search API.
  To help developers with their queries, we have defined a custom query parser to simplify the work required by transforming queries using the SOLR search engine.
• setting — Setting or system option
• talent pool — Talent pool of candidates.
• umbrella company — Umbrella company.
• user — Users are licensed system users and include customer administrator accounts. Users can be either active or in-active. Licenses are only required for active users.
• webhook — Overview

Meridian webhooks are backed by Amazon's AWS SNS (Simple Notification Service) and managed from Meridian's standard API to control webhook subscriptions per tenant account.

• Webhook URLs are registered with an AWS SNS subscription
  • Application must confirm their callback directly with AWS
  • https://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.confirm.html
• Simple JSON payload
  • Only relevant actor identifiers/information is provided
  • Use Meridian API to fetch necessary details
• Manage subscription using Meridian API webhook endpoints
  • Create, List, and Delete endpoints
• Event messages are delivered by Amazon's AWS SNS service
  • Retry policies are applied in the event of failed deliveries
• Track and retrieve failed deliveries using Meridian API webhook DLQ endpoints
  • Delivery failures are available for up to 14 days

Data Model

The following data will be delivered as a JSON object to the registered webhook URL for every event that matches a webhook subscription.

Parameter	Description
entity_type	The main entity type involved in the event. Typically one of (not limited to): candidate, company, contact, job, application, placement
action_type	Action type relevant to the event entity. Typically one of (not limited to): create, update, delete
tenant	The tenant ID where the event message comes from.
timestamp	The time the action occurred.
entity_id	The id of the main entity.
user_id	The relevant Meridian user responsible for the action
data	An object of extra data relevant to each individual webhook type. Not every webhook event type will have extra data.

Files in this folder

File	Contents
authentication.md	OAuth2 flow, token generation, refresh
search.md	SOLR-backed search query syntax
schemas.md	Shared request/response schema definitions
webhooks.md	Webhook data model and setup
changelog.md	API changelog
endpoints/activity.md	activity endpoints
endpoints/application.md	application endpoints
endpoints/candidate.md	candidate endpoints
endpoints/company.md	company endpoints
endpoints/contact.md	contact endpoints
endpoints/distribution-list.md	distribution list endpoints
endpoints/email-subscription.md	email subscription endpoints
endpoints/file.md	file endpoints
endpoints/invoice.md	invoice endpoints
endpoints/job.md	job endpoints
endpoints/placement.md	placement endpoints
endpoints/report.md	report endpoints
endpoints/reference.md	reference endpoints
endpoints/search.md	search endpoints
endpoints/setting.md	setting endpoints
endpoints/talent-pool.md	talent pool endpoints
endpoints/umbrella-company.md	umbrella company endpoints
endpoints/user.md	user endpoints
endpoints/webhook.md	webhook endpoints