# Send your first request To follow this guide, you need a demo account. Make sure it's fully setup! If not, follow our instructions on how to [create a demo account](/api/certn-api-v-1.0/getting-started/demo-account.md). ## Request ‌To communicate with our API, you'll need to build HTTP requests. You can use the programming language of your choice to achieve this. We provide examples of scripts using [Python](https://www.python.org/)![](/files/i1X0t7ez6Vlx9HiwQQXC), but most of the content you'll work with will be in [JSON](https://en.wikipedia.org/wiki/JSON)![](/files/i1X0t7ez6Vlx9HiwQQXC).‌ ### Get the URL ‌You can find the URLs for all our endpoints in the API Reference section of this documentation. Knowing how to use them can be helpful, so we'll show you how they're created.‌ In this example, you'll be making calls to our demo environment, at `https://demo-api.certn.co`.‌ We currently divide our endpoints by industry:‌ * **Human resources** endpoints start with `/hr/v1/` * **Property management** endpoints start with `/api/v2/` ‌Later on, you'll request a [Softcheck](/api/certn-api-v-1.0/guides/checks/softcheck.md), which is under `/applications`. You'll also make it a [quickscreen](/api/certn-api-v-1.0/faq.md#what-is-a-quickscreen-and-how-do-i-use-it), so you'll be filling all of the information yourself instead of sending it to your applicant. To make it a quick screen, add `/quick` to your URL.‌ Place this together, and you get the URL for your call. * Choose the URL that corresponds to your industry to continue: {% tabs %} {% tab title="Human Resources" %} ```python "https://demo-api.certn.co/hr/v1/applications/quick/" ``` {% endtab %} {% tab title="Property Management" %} ```python "https://demo-api.certn.co/api/v2/applications/quick/" ``` {% endtab %} {% endtabs %} ### Get your API key ‌[To gain access to our API](https://docs.certn.co/api/start/demo-account#setup-your-account-for-api-tests), you need an [Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)![](/files/i1X0t7ez6Vlx9HiwQQXC) with a valid Bearer token. The token is your API key. * Replace `` with your API key in the following header: ```python { "Authorization": "Bearer " } ``` {% hint style="info" %} Include this header in every call to our API, and keep it secure. It is your access key.‌ {% endhint %} ### Add the content 1. To request a Softcheck, add the request-flag `'request_softcheck': true` to your content.‌ 2. For your applicant, use our CEO's name, Andrew McLeod. 3. For the address, use our office location in Victoria, BC. 4. Fill the SIN/SSN number with a placeholder. ```python { "request_softcheck": true, "information": { "first_name": "Andrew", "last_name": "McLeod", "addresses": [ { "address": "1006 Fort St Unit 300", "city": "Victoria", "province_state": "BC", "country": "CA" } ], "sin_ssn": "123456789" }, } ``` ### Send the request ‌Now we're ready to bring it all together. Our `/application` endpoint accepts POST requests, so make sure that is what you use. Visit [W3Schools](https://www.w3schools.com/tags/ref_httpmethods.asp)![](/files/i1X0t7ez6Vlx9HiwQQXC) for useful guides on HTTP requests. Here is what your full script may look like when using Python: {% tabs %} {% tab title="Python" %} ```python import requests ### Replace with your API Key headers = { "Authorization": "Bearer " } ### Replace with the URL that corresponds to your industry url = "" content = { "request_softcheck": True, "information": { "first_name": "Andrew", "last_name": "McLeod", "addresses": [ { "address": "1006 Fort St Unit 300", "city": "Victoria", "province_state": "BC", "country": "CA" } ], "sin_ssn": "123456789" }, } # Sends the HTTP request to the API via POST response = requests.post(url, headers=headers, json=content) ############### Optional ############### # Brings errors to the forefront response.raise_for_status() # Writes the contents of the response in a file named "softcheckDemo.json" with open("softcheckDemo.json", "w") as f: f.write(response.text) ############# End Optional ############## ``` {% endtab %} {% endtabs %} In the previous example, we saved the results of the call to a new file named `softcheckDemo.json`.‌ With everything set properly and a good internet connection, you should receive a response status of `201 Created`. {% hint style="success" %} **201 Created** `[...]`\ `"id": "",`\ `[...]`\ `"report_status": "ANALYZING",`\ `[...]` {% endhint %} {% content-ref url="/pages/-MgkwA63CpdPxbzlXnZ8" %} [Retrieve the results](/api/certn-api-v-1.0/getting-started/demo-account/retrieve-results.md) {% endcontent-ref %} ## Errors ‌Errors are a relatively common occurrence when working with APIs. It's always good to know how to prevent them and what to do when they arise.‌ Here are some errors you may encounter when doing this exercise, and how to fix them.‌ ### 400 Bad Request ‌You may receive a `400 Bad Request` when:‌ * Some required fields are missing in your request {% hint style="danger" %} `"information": {`\ `"addresses": ["This field is required."]`\ `}` {% endhint %} #### How to fix this issue Add the missing fields to the [body of your request](/api/certn-api-v-1.0/getting-started/demo-account/send-request.md#add-the-content) and verify your syntax. ### 401 Unauthorized ‌You may receive a `401 Unauthorized` if:‌ * You sent your request without an authorization header {% hint style="danger" %} `"detail": "Authentication credentials were not provided."` {% endhint %} * You sent your request with an authorization header, but without an API Key * You provided an incorrect API key in the header of your request {% hint style="danger" %} `"detail": "Invalid token."` {% endhint %} #### How to fix this issue [Add your API key](/api/certn-api-v-1.0/getting-started/demo-account/send-request.md#get-your-api-key) in the authorization header, and include it in every call.‌ ### 403 Forbidden You may receive a `403 Forbidden` if: * You sent your request to an endpoint you don't have access to {% hint style="danger" %} `"detail": "You do not have permission to perform this action."` {% endhint %} #### How to fix this issue Use the URL that corresponds to [your industry](/api/certn-api-v-1.0/getting-started/demo-account/send-request.md#get-the-url). {% content-ref url="/pages/-MbvYXtBnywVTALaZNg\_" %} [Error codes](/api/certn-api-v-1.0/api-reference/resources/error-codes.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.certn.co/api/certn-api-v-1.0/getting-started/demo-account/send-request.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.