{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"e935c989-3e9b-4c96-ad11-25ac9b3478b7","name":"B2B Endpoints (Published)","description":"# Getting Started\n\nTo get up and running rapidly, we encourage you to take 10 minutes reading some of the following information. We see these first two items as mandatory, without these you won't get very far:\n\n\\*   Whats my URL\n\\*   Creating an App\n    \n\nIf you have previously implemented web services nothing here should be new. First, you need to know your URL, and, you will need an App. As your URL is really important, we decided to explain this first, so, read **whats my URL**. Then, read **creating an App**, your app will need privileges, these privileges are also explained in **creating an App**.\n\nWe have also explained some of our conventions and provided some examples, if you want to read through these, please do:\n\n\\*   Conventions\n\\*   Whitelist\n\\*   Examples\n    \n\n# Whats my URL?\n\nLet there be no confusion we **do not accept** non SSL (TLS) traffic it’s all **https**. Please don't try http, you won't get very far.\n\nLet’s start with a completed URL and break this down:\n\n[https://api.corehr.com/ws/tenant/corehr/v1/reference/type/COST/](https://api.corehr.com/ws/tenant/corehr/v1/reference/type/COST/)\n\nOR\n\n[https://uatapi.corehr.com/ws/tenant/corehr/v1/reference/type/COST/](https://uatapi.corehr.com/ws/tenant/corehr/v1/reference/type/COST/)\n\n## This paragraph explains all about the URL\n\nThis example is using the web service defined by `GET /reference/type/:atype/:code?\\*`\n\nAll URL's will begin with either [_https://api.corehr.com/ws/_](https://api.corehr.com/ws/) or [_https://uatapi.corehr.com/ws/_](https://uatapi.corehr.com/ws/), we think it's obvious what the difference is here - one is for production and the other is for UAT. And, as we need to know who you are, we call this the _tenant_ (your tenant name can be supplied by your PeopleXD representative, or you can find the tenant name based on your portal URL, e.g., if your Portal URL is [https://my.corehr.com/pls/coreportal_acmep/](https://my.corehr.com/pls/coreportal_acmep/)... then your tenant name is \\[acmep\\], now _acmep_ is not actually a real tenant, it’s just for illustration). Your Portal URL could of course be from the UAT environment for example [https://uatmy.corehr.com/pls/coreportal_acmeu/](https://uatmy.corehr.com/pls/coreportal_acmeu/) then your tenant name is \\[acmeu\\], now _acmeu_ is not actually a real tenant, it’s just for illustration). After your tenant we have a constant _corehr/v1_ (never change this, just go with it). At this point we have [_https://api.corehr.com/ws/acmep/corehr/v1/_](https://api.corehr.com/ws/acmep/corehr/v1/) or [_https://uatapi.corehr.com/ws/acmeu/corehr/v1/_](https://uatapi.corehr.com/ws/acmeu/corehr/v1/) (remember acmep and acmeu are only for this example - they do not really exist). Next we need to know the specific web service end point you want to execute, in this example we are using the end point _/reference/type/:atype/:code?_ where :atype and :code are bind variables, and, in our example we are interested in cost centres and the type _cost_ represents cost centres, and we have not used the optional bind variable :code?. The `?` indicates the parameter is optional, we used decided in this example not to implement.\n\n### Step by Step breakdown\n\nLet’s explain the URL again, but this time take it bit by bit. All requests to our servers should be **https**. All **non SSL/(TLS)** requests are ignored. Let's start with the URL:\n\n> [https://api.corehr.com/ws/tenant/corehr/v1/reference/type/COST/](https://api.corehr.com/ws/tenant/corehr/v1/reference/type/COST/)\n\n\\*   api.corehr.com\n    \n\nrepresents the root of all web service requests. When testing, we have specific environments typically we referred to these environments as UAT environments, and the root of the UAT environment is aptly named: `uatapi.corehr.com`.\n\n\\*   /ws/\n    \n\nindicates web services\n\n\\*   /tenant/\n    \n\nindicates the name of your tenant. Your tenant name can be supplied by your PeopleXD representative, or you can find the tenant name based on your portal URL, e.g., if your Portal URL is [https://my.corehr.com/pls/coreportal_acmep/](https://my.corehr.com/pls/coreportal_acmep/)... then your tenant name is \\[acmep\\], now _acmep_ is not actually a real tenant, it’s just for illustration). Your CorePortal URL could of course be from the UAT environment for example [https://uatmy.corehr.com/pls/coreportal_acmeu/](https://uatmy.corehr.com/pls/coreportal_acmeu/) then your tenant name is \\[acmeu\\], now _acmeu_ is not actually a real tenant, it’s just for illustration)\n\n\\*   /corehr/\n    \n\nthis lets us know more information about where you are trying to get to, you don’t need to change this, just go with the value _corehr_\n\n\\*   /v1/\n    \n\nindicates versioning, right now /v1/ is the only option, this does not represent PeopleXD versions, instead represents our web services framework.\n\n\\*   /reference/\n    \n\nrepresents the module, in this example the module is /reference/\n\n\\*   : (colon)\n    \n\nrepresents parameters aka bind parameters. And, with the parameters added is `/reference/type/COST/`. In this example we are dealing with cost centres, and they are represented by the bind variable _COST_\n\n\\*   ? (question mark)\n    \n\nSometimes (though not in this example) you might see a bind variable represent with a ? mark, this indicates an optional bind parameter. An example of an optional bind variable would be defined as `/reference/type/:atype/:code?`\n\n\\*   :atype\n    \n\nrepresents a mandatory parameter in this example\n\n\\*   :code?\n    \n\nrepresents an optional parameter in this example\n\nIn the example :atype is `COST` while :code? is not used. To extend and use the optional parameter the endPoint would appear as follows `/reference/type/COST/100`\n\nAnd, the entire URL would appear as follows for the tenant acmep\n\n[https://api.corehr.com.com/ws/acmep/corehr/v1/reference/type/COST/](https://api.corehr.com.com/ws/acmep/corehr/v1/reference/type/COST/)\n\nand, with the optional parameter it would be\n\n[https://api.corehr.com/ws/acmep/corehr/v1/reference/type/COST/100](https://api.corehr.com/ws/acmep/corehr/v1/reference/type/COST/100)\n\nAnd, if you are using the UAT environment then\n\n[https://uatapi.corehr.com.com/ws/acmeu/corehr/v1/reference/type/COST/](https://uatapi.corehr.com.com/ws/acmeu/corehr/v1/reference/type/COST/)\n\nAnd, if you are using the UAR environment then\n\n[https://uatapi.corehr.com/ws/acmeu/corehr/v1/reference/type/COST/100](https://uatapi.corehr.com/ws/acmeu/corehr/v1/reference/type/COST/100)\n\n---\n\n# Creating an App\n\nAuthentication is based on oAuth 2 client credentials flow. To make requests you will need an oAuth App, you must be granted an App by your system administrator (PeopleXD do **not** provide these details). Your system administration can follow these steps to create an App. Don't forget you do need to read **whats your URL**. All third party applications will require a clientId and client secret (this is like a username / password combination).\n\nUsing the Client ID and Secret, a request is made to the authentication token end point, an access token is provided on successful authentication. This access token is required for each request and is included as part of the request header.\n\n### oAuth App Creation - Getting the Credentials\n\nUsing the Security module in CorePortal (your administration account will need to have access to this important module). Once in the Security Module, select the Web Service App tab. Select the option **create new application** and fill in the details. Once the App is created, click on the \"View Credentials\" option to view the Client ID and the Secret for a particular application.\n\n<img src=\"https://api.corehr.com/resources/WebServiceCredentials.png\" alt=\"\">\n\nCredentials are initially displayed in a masked format however clicking the \"Unmask Credentials\" button will show you the full text of the Client ID and Secret for this App for use by the token service. Of course, don't forget these are important credentials, the client secret should be kept secret. Do not include these credentials when sending emails or store them is open source projects.\n\n<img src=\"https://api.corehr.com/resources/UnmaskWebServiceCredentials2.png\" alt=\"\">\n\n### oAuth App Creation - Assigning the Privileges\n\nAn app must be granted some privileges otherwise you won’t get very far, we do not make any assumptions as to what privileges to be assigned i.e., they must be explicitly granted. Do this by selecting the Update Web Service Privileges for that App. In the next example, all the end points for the “Image” web services are selected along with the “HelloWorld” web service.\n\n<img src=\"https://api.corehr.com/resources/GrantWebServicePrivs.png\" alt=\"\">\n\n### Getting a Token\n\nUsing the newly created App, you now need to get a token using the clientID and Client Secret. The token authentication end point is slightly different i.e., it does not include /v1/. If you have read the **whats your URL** section, you should know your URL at this point, and the oauth token can be accessed via the /oauth/token end point. If your tenant was named _acmep_ then you can get a token from:\n\n[https://api.corehr.com/ws/acmep/corehr/oauth/token](https://api.corehr.com/ws/acmep/corehr/oauth/token)\n\nand for UAT the URL is:\n\n[https://uatapi.corehr.com/ws/acmeu/corehr/oauth/token](https://uatapi.corehr.com/ws/acmeu/corehr/oauth/token)\n\n# Using CURL to get a token\n\n\\*   Client ID `Nn4sgf0yXCYcfPpUIo7NxQ..`\n\\*   Client Secret `gPDvI3HPvFiSucge84rKkw..`\n    \n\nThese are not actually real credentials do not try and use these credentials, instead use the credentials obtained from the _creating an app_ section.\n\nClientID and Secret are separated by a colon, this is important, failing to use this separator results in failed authentication. Grant type should be set to client_credentials.\n\n> curl -i --user Nn4sgf0yXCYcfPpUIo7NxQ..:gPDvI3HPvFiSucge84rKkw.. --data \"grant_type=client_credentials\" [https://api.corehr.com/ws/acmep/corehr/oauth/token](https://api.corehr.com/ws/acmep/corehr/oauth/token)\n\nAND, for UAT\n\n> curl -i --user Nn4sgf0yXCYcfPpUIo7NxQ..:gPDvI3HPvFiSucge84rKkw.. --data \"grant_type=client_credentials\" [https://uatapi.corehr.com/ws/acmeu/corehr/oauth/token](https://uatapi.corehr.com/ws/acmeu/corehr/oauth/token)\n\nReturns a JSON object, with the access token\n\n{\n\n\"access_token\":\"KqWt7F2oXOZaInnrt0b7NQ..\",\n\n\"token_type\":\"bearer\",\n\n\"expires_in\":3600\n\n}\n\nAll subsequent requests must now use this access token (expires in 3600 seconds i.e. 60 minutes). Add this access token as an Authorization header.\n\n### Using the Token to get some data\n\nThis example uses a token with the contacts module, remember your App needs to have the PRIVS for the contact module (this is explained in the section _oAuth App Creation - Assigning the Privileges_)\n\n> curl -i -H\"Authorization: Bearer KqWt7F2oXOZaInnrt0b7NQ..\" [https://api.corehr.com/ws/acmep/corehr/v1/contact/](https://api.corehr.com/ws/acmep/corehr/v1/contact/)\n\nAND, for UAT\n\n> curl -i -H\"Authorization: Bearer KqWt7F2oXOZaInnrt0b7NQ..\" [https://uatapi.corehr.com/ws/acmeu/corehr/v1/contact/](https://uatapi.corehr.com/ws/acmeu/corehr/v1/contact/)\n\n---\n\n# Conventions\n\n## JSON\n\nThis section is optional to read, it does raise some important conventions. All web service content are **JSON** (apart from services such as images). A request body must be well formed JSON and all responses from server will be JSON. JSON is expected to be well formed, adhering to ECMA 404 standard, PeopleXD implements strict JSON.\n\nAll requests with a request body (POST and PATCH) will require a header with `content-type` set to `application/json`, this can be seen in the examples below. All other `content-type` requests will be rejected (apart from cases such as images). Following two resources are useful when parsing JSON.\n\n[JSON Lint](http://jsonlint.com/)\n\n[EMCA404 Specification](http://www.ecma-international.org/publications/standards/Ecma-404.htm)\n\n## HTTP Verbs\n\nPeopleXD use the following verbs for all web services:\n\n\\*   POST creating new content\n\\*   PATCH updating existing content\n\\*   GET retrieve existing content\n\\*   DEL delete existing content\n    \n\nAll other Verbs will return as an error.\n\n## Pagination and Limits\n\nAll web services have a default **limit of 100** objects returned. Any instances where more than 100 objects exist (e.g. could be common to have a large set of cost centres), the response body will include a link array with additional links for pagination. Though it is possible to set a pagesize of more than 100, using the pagesize query parameter.\n\nEach GET request includes following\n\n\\*   limit\n    \n\nrepresents the maximum number of records returned in one request i.e. 100.\n\n\\*   offsetby\n    \n\nrepresents pagination, the first request will always have an offsetby 0 i.e. the start. Where more than the limit exists offsetby controls the starting position, typically in batches of 100. Each GET request can accept the offsetby parameter.\n\n\\*   count\n    \n\nthe number of records for this response, the maximum count will equal the limit parameter i.e. 100.\n\n\\*   hasMore\n    \n\na boolean representation indicating if more records exist.\n\n\\*   links\n    \n\nincludes links to first and next. The next link is used when pagination is discovered i.e. more than the limit per request.\n\n## Error Handling & Success Responses\n\nEach module below defines error codes and descriptions. Our approach is to use standard HTTP status error codes (typically 4xx) in addition to more verbose / precise errors contained in the response body. The HTTP status codes are returned in the HTTP response header as standard, while the verbose error code is contained in the response body.\n\nThe Convention for documenting the HTTP status code and verbose error code is\n\nHTTP Status Code / Verbose Error Code\n\n> example from Contacts Module\n\n> 400 / 001 Mandatory fields are missing\n\nIndicates a HTTP Status Code of `400 - Bad Request -` and returned via HTTP response header. While `001 Mandatory fields are missing` is the verbose error, and returned in the response body.\n\nIn this example the bad request was flagged because a mandatory field is not included in the request.\n\nListed below are the standard HTTP response codes used throughout PeopleXD Web Services.\n\n\\*   400 - Bad Request -\n    \n\nTypically means the request is not complete, this could mean missing data or the data provided is invalid.\n\n\\*   401 - Unauthorized -\n    \n\nTypically indicates an unauthorized request using invalid credentials. oAuth 2 Client Credentials are required to access protected resources.\n\n\\*   404 - Not Found -\n    \n\nTypically indicates an entity (person, cost centre, or some object) does not exist.\n\n\\*   405 - Method Not Allowed -\n    \n\nOnly `GET`, `POST` and `PATCH` methods are supported.\n\n\\*   415 - Invalid Content Type -\n    \n\nOnly `application/json` accepted for POST and PATCH.\n\n## Success Messages\n\n\\*   200 - OK -\n    \n\nTypical response for `GET` method.\n\n\\*   201 - Created -\n    \n\nTypical response for `POST` or `PATCH` methods.\n\n---\n\n# Whiltelists\n\nA number of the PeopleXD modules implement a whitelist to access data, for example the reference module allows accessing all reference data, there are over 150 distinct refernce types such as Cost Centres, Departments, Work Groups etc. The use case for the B2B web service integration may only have a requirement to deal with Cost Centres. If that is the case the whitelist is the solution. Whitelists can be managed in the Security Module in the same place as managing App Creation.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"3101638","collectionId":"e935c989-3e9b-4c96-ad11-25ac9b3478b7","publishedId":"TzeTHUDu","public":true,"publicUrl":"https://documenter-api.postman.tech/view/3101638/TzeTHUDu","privateUrl":"https://go.postman.co/documentation/3101638-e935c989-3e9b-4c96-ad11-25ac9b3478b7","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2021-06-11T10:32:21.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/TzeTHUDu"}