Integration guide

How to plan and build an integration with Prophy: what to implement, how a manuscript goes through it, and what to set up before you go live.

Choose your integration level

The integration is built in three levels. Each level adds to the previous one and removes another part of the manual work.

Level	Problem solved	What you implement
Results in your system	Creating folders by hand, copying manuscripts from your system to Prophy	Send each manuscript to the Manuscript upload API and show the returned candidates to the editor.
One click into Prophy	Separate registration, one more login and password, setting up access rights by hand	Add a "Go to Prophy" button that logs the editor in with a signed JWT. See User login.
The selection comes back	Copying the selected reviewers back to your system	Receive the Mark as manuscript referee webhook and add the reviewers to the manuscript, so the editor can invite them.

Each level can be built on its own, and most integrations start with Results in your system. We recommend implementing all three levels. Results in your system alone works when the first candidates are good enough. When they are not, the editor needs Referee Finder in Prophy: there they can focus the search on a specific topic or method and use the advanced filters. The API takes only basic filters, such as h-index, academic age and the number of articles, so One click into Prophy takes the editor to Prophy instead, and The selection comes back brings their choice back without copying names or emails.

Integration workflow

This is how one manuscript goes from your system to Prophy and back.

#	Who	What happens	Integration level	API
1.	Your system	A manuscript reaches the reviewer selection stage	—	—
2.	Your system	Uploads the manuscript with your internal identifier as origin_id and the journal as folder. Prophy creates the folder if it doesn't exist and returns reviewer candidates.	Results in your system	Manuscript upload
3.	Your system	Shows the candidates to the editor	Results in your system	—
4.	Editor	Clicks "Go to Prophy". Your backend signs a JWT at the moment of the click and redirects the editor to Prophy.	One click into Prophy	User login
5.	Editor	Refines the search in Referee Finder and marks suitable reviewers	—	—
6.	Prophy	Sends the current list of marked reviewers each time the editor marks or unmarks one	The selection comes back	Webhook
7.	Editor	Sends invitations to the reviewers from your system	—	—

Each manuscript is billed once. Requests rejected with an error, such as 400 or 401, are not billed, and uploading a manuscript again with the same origin_id is free.

Set up your integration

All credentials and settings are on the Integrations dashboard. It is available to users with the Integrations admin permission.

Integration level	What you need	Where on the dashboard
Results in your system	API Key	API Keys
One click into Prophy	JWT Key, JWT Sub, Organization Code	API Keys
The selection comes back	Webhook URL and its Webhook API Key, delivery logs	Webhooks

• Testing. Prophy has no separate test environment. Send test manuscripts to a dedicated test folder, and use a second API Key for development. You may also contact your Prophy account manager to set up a separate development organization if that suits you better.
• Key rotation. Both API Key and JWT Key allow two active keys at once, so you can switch to a new key without downtime and then delete the old one.
• Manuscript retention. An organization administrator sets how long manuscripts are kept in Data lifecycle → Retention rules of the organization settings.
• Several organizations. If you integrate Prophy for several client organizations, each of them has its own credentials.
• Editor access. By default, an editor who logs in with a JWT gets access to all manuscripts in the folder. To give access to one manuscript for a limited time, add temp-access-until to the JWT. See User login.
• Security. Where the data is stored and how it is protected is described in the Trust Center. Prophy doesn't train any models on your data.

Identifiers

These identifiers connect records in your system with records in Prophy.

Identifier	What it is	You send it in	Prophy returns it in
origin_id	Your manuscript ID	Manuscript upload, User login, Recommend journals	Manuscript upload response, webhook
folder	Journal name, shown to editors as a folder in Prophy	Manuscript upload, User login	Recommend journals as folder_name
manuscript_id	Manuscript ID in Prophy	—	Manuscript upload response, webhook
author_id	Prophy author ID of a reviewer candidate	User login as author_id or custom_author_id	Candidates in the Manuscript upload response and in the webhook
client_id	Your ID for a person in an Authors group	Authors from group	authors_groups of the candidates in the Manuscript upload response and in the webhook

• Match manuscripts by origin_id. The webhook carries the origin_id you sent.
• Store the manuscript_id. Keep it next to the manuscript in your system to know which manuscripts were sent to Prophy.
• Keep the author_id of each reviewer. The webhook sends the whole list of marked reviewers every time, so compare it with the previous list to see who was added and who was removed.
• Match candidates with your own reviewer pool. If your system keeps its own pool of reviewers and you want to match Prophy's candidates with it, there are two ways:
  • Create an Authors group with your reviewers. Prophy then returns your client_id on each candidate who is in the group.
  • Match the candidates yourself by email, orcid, name and affiliation, then store the author_id with the reviewer: the next time this candidate comes, match by author_id.

API versions

Responses and webhooks include a version field, and the reference pages mark fields with the version that added them. New versions only add fields: existing fields are not removed or changed, so your integration keeps working when Prophy releases a new version.

Optional features

These APIs are not needed for the main workflow, but can add to it.

Feature	What it gives you	API
Your own pool of experts	Upload your reviewers or editors to an Authors group and link it to a journal folder in its Referee Finder settings. You can set Prophy to look for candidates only in this group, or to boost and highlight them among all candidates.	Authors groups, Authors from group
Your own attributes	Upload your data about experts in Authors groups that you use when choosing editors and reviewers.	Custom fields, Authors from group
Journal recommendations	Find the journals that suit an uploaded manuscript best.	Recommend journals

Going live

Before going live

• Run one manuscript through the whole workflow in the test folder: upload it, open it in Prophy with the "Go to Prophy" button, mark a reviewer and check that the webhook arrives.

After going live

• If you no longer need the development API Key and JWT Key, delete them on the Integrations dashboard. If you keep them for testing, protect them like the production keys.

If something doesn't work, see Troubleshooting.