{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Getting Started","description":"API documentation for the Bright Customer API, providing comprehensive guides and reference materials for developers integrating with Bright products.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started","__idx":0},"children":["Getting Started"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-create-an-application","__idx":1},"children":["1. Create an Application"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prerequisites:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A BrightHR administrator account"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create an API application:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Browse to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://account.brighthr.com/manage-api"},"children":["API Management"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create new application"]}," click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Give your application a name and create it"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Under that application you just created, note the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client ID"]}," and then click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create Secret"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Copy the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Secret"]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important:"]}," Store your client secret securely. You will not be able to view it again after closing the dialog."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-obtain-a-bearer-token","__idx":2},"children":["2. Obtain a Bearer Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API uses OAuth2 client credentials flow for authentication."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To make a request to the API, you will first need to obtain a bearer token by following these steps:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the client id and secret from your application"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Make a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://login.brighthr.com/connect/token"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The request body must include:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_credentials"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},": your client id"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},": your client secret"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}," must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/x-www-form-urlencoded"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request","__idx":3},"children":["Example Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://login.brighthr.com/connect/token \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response","__idx":4},"children":["Example Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"access_token\": \"eyJhbGciOiJSUzI1NiIs...\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 3600\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"using-the-token","__idx":5},"children":["Using the Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have the bearer token, include it in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header of every API request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Authorization: Bearer YOUR_BEARER_TOKEN\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A bearer token is valid for 1 hour. Once it expires, you will need to obtain a new token by repeating the authentication process. If you make a request with an expired token, you will receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," error with the problem type ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/problems#token-expired"},"children":["TokenExpired"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-making-your-first-request","__idx":6},"children":["3. Making Your First Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have a bearer token, you can make your first API request. The following example calls the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["List Employees"]}," endpoint, which returns a list of employees in your organisation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request-1","__idx":7},"children":["Example Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.bright.hr/employees/v1/query \\\n  -H \"Authorization: Bearer YOUR_BEARER_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response-1","__idx":8},"children":["Example Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"items\": [\n    {\n      \"id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n      \"name\": {\n        \"givenName\": \"Jane\",\n        \"familyName\": \"Smith\"\n      },\n      \"employment\": {\n        \"jobTitle\": \"Software Engineer\",\n        \"start\": \"2023-01-15\",\n        \"end\": null\n      },\n      \"email\": \"jane.smith@example.com\",\n      \"externalReference\": null,\n      \"_metadata\": {\n        \"isRegistered\": true,\n        \"isTerminated\": false\n      }\n    }\n  ],\n  \"continuationToken\": null\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Getting Started","id":"getting-started","depth":1},{"value":"1. Create an Application","id":"1-create-an-application","depth":2},{"value":"2. Obtain a Bearer Token","id":"2-obtain-a-bearer-token","depth":2},{"value":"Example Request","id":"example-request","depth":3},{"value":"Example Response","id":"example-response","depth":3},{"value":"Using the Token","id":"using-the-token","depth":3},{"value":"3. Making Your First Request","id":"3-making-your-first-request","depth":2},{"value":"Example Request","id":"example-request-1","depth":3},{"value":"Example Response","id":"example-response-1","depth":3}],"frontmatter":{"slug":["/gettingstarted"],"seo":{"title":"Getting Started"}},"lastModified":"2026-05-13T14:32:09.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/gettingstarted","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}