Publons Reviewer Connect

{"swagger":"2.0","info":{"title":"Publons Reviewer Connect","description":"Publons Reviewer Connect helps you to find, screen, and contact expert peer reviewers for your manuscripts or grant applications.\n\nThis API helps you to integrate Publons Reviewer Connect directly into your editorial or grant management system.","contact":{"name":"Publons","email":"reviewer-connect@publons.com"},"version":"2.0.0"},"host":"api.clarivate.com","basePath":"/reviewer-connect/api","schemes":["https"],"consumes":["application/json"],"produces":["application/json"],"paths":{"/":{"post":{"tags":["Publons Reviewer Connect API"],"summary":"Generate reviewer recommendations for your manuscript or grant application.","parameters":[{"name":"Search input","in":"body","description":"The API accepts the following parameters as JSON POST data.\n * Search input: Manuscript or grant application details.\n * Search filters: Excluded reviewers and filter countries.\n * Search configuration: Search years and number of recommendations to fetch.","required":true,"schema":{"$ref":"#/definitions/Request"}}],"responses":{"200":{"description":"Successful response containing reviewer recommendations and search meta data.","schema":{"$ref":"#/definitions/Response"}},"400":{"description":"Bad request response containing error information.","schema":{"$ref":"#/definitions/400Response"}}}}}},"definitions":{"Request":{"type":"object","required":["searchArticle"],"properties":{"requestId":{"description":"Optional consumer-defined request identifier. If provided in the request, will be returned in the response.","type":"string"},"searchArticle":{"$ref":"#/definitions/SearchArticle"},"excludedReviewers":{"type":"array","description":"List of additional individuals to exclude from the recommendations. Note that it is not necessary to re-list 'authors' here as they will already be excluded from the recommendations. Unlike 'authors', 'excludedReviewers' will not be used for conflict of interest checks.","items":{"$ref":"#/definitions/ExcludedReviewer"}},"searchYears":{"type":"integer","description":"Base reviewer recommendations on Web of Science publications published within the last 3, 4, or 5 years.","default":3,"minimum":3,"maximum":5},"numRecommendations":{"type":"integer","description":"Number of recommendations to fetch. Note that the API will not always return the full number of recommendations requested.","default":30,"minimum":15,"maximum":100},"includedCountries":{"type":"array","description":"If provided, reviewer recommendations will be restricted to researchers recently affiliated with organizations from the listed countries. 'includedCountries' and 'excludedCountries' should not be used in conjunction.","items":{"$ref":"#/definitions/Country"}},"excludedCountries":{"type":"array","description":"If provided, reviewer recommendations will be restricted to researchers without recent affiliations with organizations from the listed countries. 'includedCountries' and 'excludedCountries' should not be used in conjunction.","items":{"$ref":"#/definitions/Country"}}}},"SearchArticle":{"type":"object","description":"Input manuscript or grant application details.","required":["title","abstract","journal"],"properties":{"title":{"type":"string","example":"Manuscript or grant application title"},"abstract":{"type":"string","example":"Manuscript or grant application abstract"},"journal":{"$ref":"#/definitions/JournalOrFunder"},"authors":{"type":"array","description":"List of manuscript authors or grant application applicants. Will be excluded from the recommendations. Will also be used to check for potential conflicts of interest by co-publication or co-affiliation.","items":{"$ref":"#/definitions/AuthorOrApplicant"}}}},"JournalOrFunder":{"type":"object","description":"Journal or funding agency.","required":["name"],"properties":{"name":{"type":"string","example":"Journal or funding agency name"}}},"AuthorOrApplicant":{"type":"object","required":["firstName","lastName"],"properties":{"firstName":{"type":"string","example":"Researcher first name"},"lastName":{"type":"string","example":"Researcher last name"},"email":{"type":"string","format":"email","example":"researcher@organization.edu"},"organizations":{"type":"array","description":"Affiliated organizations. Used to check for potential conflicts of interest by co-affiliation.","items":{"$ref":"#/definitions/AuthorOrganization"}}}},"AuthorOrganization":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Affiliated organization name"}}},"ExcludedReviewer":{"type":"object","required":["firstName","lastName"],"properties":{"firstName":{"type":"string","example":"Researcher first name"},"lastName":{"type":"string","example":"Researcher last name"},"email":{"type":"string","format":"email","example":"researcher@organization.edu"}}},"Country":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Country name"}}},"Response":{"type":"object","required":["searchToken","searchUrl","recommendedReviewers"],"properties":{"requestId":{"type":"string","description":"Optional consumer defined request identifier. If provided in a request, will be returned in the response."},"searchToken":{"type":"string","description":"Unique token identifying this search. When trouble-shooting or enquiring about a particular search with the Web of Science team please provide the search token in question.","example":"7dd6f44b0b9346f6b75d6d0efb65ebc2"},"searchUrl":{"type":"string","description":"URL for viewing and interacting with this search within the Web of Science Reviewer Locator web interface. Note that web interface permissions are required and are separate to your API key.","format":"url","example":"https://publons.com/partner/reviewer-connect/7dd6f44b0b9346f6b75d6d0efb65ebc2/"},"viewOnPublonsUrl":{"type":"string","description":"DEPRECATED. Please use 'searchUrl' instead.","format":"url"},"recommendedReviewers":{"type":"array","items":{"$ref":"#/definitions/RecommendedReviewer"}}}},"RecommendedReviewer":{"type":"object","properties":{"rank":{"type":"integer","description":"Recommended reviewers are ordered and ranked numerically by relevance as determined by the Web of Science Reviewer Locator recommendation algorithm.","example":1},"firstName":{"type":"string","example":"Researcher first name"},"lastName":{"type":"string","example":"Researcher last name"},"publishingName":{"type":"string","description":"DEPRECATED. Please use 'firstName' and 'lastName' instead.","example":"Researcher full name"},"profileUrl":{"type":"string","description":"URL for viewing this researcher's full Publons profile.","format":"url","example":"https://publons.com/researcher/A-0000-2019"},"researcherId":{"type":"string","format":"ResearcherID","example":"A-0000-2019"},"orcid":{"type":"string","format":"ORCID","example":"0000-0000-0000-0001"},"bio":{"type":"string","description":"DEPRECATED."},"recentOrganizations":{"type":"array","description":"Affiliated organizations within the Web of Science.","items":{"$ref":"#/definitions/Organization"}},"contact":{"type":"object","required":["availableToReview","emails"],"properties":{"emails":{"type":"array","description":"Latest Web of Science Author Record contact email address.","items":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","example":"researcher@university.edu"}}}},"availableToReview":{"type":"string","description":"DEPRECATED.","enum":["available","unavailable","YYYY-MM-DD"],"example":"available"}}},"numWosArticles":{"type":"integer","description":"Number of authored publications within the Web of Science.","example":1},"relevantArticles":{"type":"array","description":"Top three relevant authored publications within the Web of Science as determined by the Web of Science Reviewer Locator recommendation algorithm.","items":{"$ref":"#/definitions/Article"}},"keywords":{"type":"array","description":"Web of Science Author Record keywords.","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Research keyword"}}}},"numVerifiedReviews":{"type":"integer","description":"Number of verified reviews on this researcher's Publons profile.","example":1},"reviewerExperience":{"type":"array","description":"Number of verified reviews on this researcher's Publons profile broken down by journal.","items":{"type":"object","required":["journal","numVerifiedReviews"],"properties":{"journal":{"$ref":"#/definitions/Journal"},"numVerifiedReviews":{"type":"integer","description":"Number of verified reviews on this researcher's Publons profile for this journal.","example":1}}}},"editorialBoards":{"type":"array","description":"Editorial boards listed on this researcher's Publons profile.","items":{"type":"object","required":["journal"],"properties":{"journal":{"$ref":"#/definitions/Journal"}}}},"grantReviewExperience":{"type":"array","description":"Number of verified grant reviews on this researcher's Publons profile broken down by funding agency.","items":{"type":"object","required":["funder","numGrantReviews"],"properties":{"funder":{"$ref":"#/definitions/Funder"},"numGrantReviews":{"type":"integer","description":"Number of verified reviews on this researcher's Publons profile for this funding agency.","example":1}}}},"publonsAcademy":{"type":"string","description":"Indicates whether the recommended reviewer is a Publons Academy graduate, mentor, or both.","enum":["Graduate","Mentor","Graduate and mentor"],"example":"Graduate"},"conflictOfInterestArticles":{"type":"array","description":"Authored publications within the Web of Science which represent a potential conflict of interest by co-publication with the search manuscript / grant application's authors / applicants.","items":{"$ref":"#/definitions/Article"}},"conflictOfInterestOrganizations":{"type":"array","description":"Affiliated organizations within the Web of Science which represent a potential conflict of interest by co-affiliation with the search manuscript / grant application's authors / applicants.","items":{"$ref":"#/definitions/Organization"}}}},"Organization":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Organization name"},"url":{"type":"string","format":"url"},"firstYear":{"type":"string","description":"First year of affiliation with this organization according to Web of Science publication data.","format":"YYYY","example":"2019"},"lastYear":{"type":"string","description":"Last year of affiliation with this organization according to Web of Science publication data.","format":"YYYY","example":"2021"},"address":{"type":"string"},"country":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"}}},"Article":{"type":"object","required":["title","ut","journal","authors"],"properties":{"title":{"type":"string","example":"Publication title"},"doi":{"type":"string","format":"DOI","example":"10.123/example.456"},"ut":{"type":"string","format":"UT","example":"WOS:000000000000001"},"journal":{"$ref":"#/definitions/Journal"},"authors":{"type":"array","items":{"type":"object","required":["firstName","lastName"],"properties":{"firstName":{"type":"string","example":"Researcher first name"},"lastName":{"type":"string","example":"Researcher last name"},"publishingName":{"type":"string","description":"DEPRECATED. Please use 'firstName' and 'lastName' instead.","example":"Researcher full name"}}}},"publicationYear":{"type":"string","format":"YYYY","example":"2019"}}},"Journal":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Journal name"}}},"Funder":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Funding agency name"}}},"400Response":{"type":"object","properties":{}}},"tags":[{"name":"Publons Reviewer Connect API"}],"externalDocs":{"description":"Read more about Publons Reviewer Connect","url":"https://publons.com/benefits/reviewer-connect"},"securityDefinitions":{"key":{"type":"apiKey","in":"header","name":"X-ApiKey"}},"security":[{"key":[]}]}