# Create Your First API Call

{% hint style="success" %}
**Audience:** Developers

**Purpose:** Provides step-by-step instructions for making an authenticated request to the <code class="expression">space.vars.Kizen\_company\_name</code> API using an API Key, Business ID, and User ID, using the Retrieve <code class="expression">space.vars.object</code> Details by ID endpoint as a working example.
{% endhint %}

## Overview

Now that you have your API credentials, you are ready to make your first authenticated request to the <code class="expression">space.vars.Kizen\_company\_name</code> API. This topic walks you through assembling your credentials, choosing an endpoint, and executing a live API call using the [Retrieve Object Details by ID](https://developer.kizen.com/docs/concepts/objects/object-apis/retrieve-object-details-by-id-api) endpoint as an example.

### Before You Begin

Before starting this topic, ensure you have the following ready:

* Your **API Key**, **Business ID**, and **User ID** from the **API Connections** page
* A created <code class="expression">space.vars.object</code> in your <code class="expression">space.vars.Kizen\_company\_name</code> platform. If you have not yet created one, see [Create Your First Object](https://developer.kizen.com/docs/kizen-basics/kizen-in-action/create-your-first-object-or-kizen-basics)
* <code class="expression">space.vars.entity</code> details in your <code class="expression">space.vars.object</code>. If you have not yet created any, see [Create Your First Record](https://developer.kizen.com/docs/kizen-basics/kizen-in-action/create-your-first-record-or-kizen-basics)
* The **Object ID** of the <code class="expression">space.vars.object</code> you want to retrieve — this is a UUID found in your <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.object</code> settings
* An HTTP client such as cURL, Postman, or any language-specific (e.g., Python requests, JavaScript fetch) HTTP library

### About the Example Endpoint

This topic uses the [Retrieve Object Details by ID](https://developer.kizen.com/docs/concepts/objects/object-apis/retrieve-object-details-by-id-api) endpoint as the example call. This endpoint returns the full schema definition for a single <code class="expression">space.vars.object</code> in your business, including its fields, categories, and relationship configuration. It is a safe, read-only call and will not modify any data.

|              |                                                                  |
| ------------ | ---------------------------------------------------------------- |
| **Method**   | `GET`                                                            |
| **Endpoint** | `/api/custom-objects/{object_pk}/detail`                         |
| **Full URL** | `https://app.go.kizen.com/api/custom-objects/{object_pk}/detail` |

Replace `{object_pk}` with the UUID of the <code class="expression">space.vars.object</code> you want to retrieve.

***

## Create Your First API Call

{% stepper %}
{% step %}

#### Assemble your request headers

Every <code class="expression">space.vars.Kizen\_company\_name</code> API call requires the same three headers. Pull these from the credentials you generated in [Generate API Credentials](https://developer.kizen.com/docs/developers/building-with-apis/generating-api-credentials):

| Header          | Value            |
| --------------- | ---------------- |
| `X-API-KEY`     | Your API Key     |
| `X-BUSINESS-ID` | Your Business ID |
| `X-USER-ID`     | Your User ID     |
| `accept`        | application/json |
| {% endstep %}   |                  |

{% step %}

#### Make the request

Choose your preferred tool below. Replace the placeholder values with your actual credentials and the <code class="expression">space.vars.object</code>'s `entity_id`, which you can find in the **General Settings** page of the <code class="expression">space.vars.object</code> when viewing it in edit mode.

{% tabs %}
{% tab title="cURL" %}

```
cURL -X GET "https://app.go.kizen.com/api/custom-objects/{object_pk}/detail" \
  -H "accept: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-BUSINESS-ID: your_business_id_here" \
  -H "X-USER-ID: your_user_id_here"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://app.go.kizen.com/api/custom-objects/{object_pk}/detail"

headers = {
    "accept": "application/json",
    "X-API-KEY": "your_api_key_here",
    "X-BUSINESS-ID": "your_business_id_here",
    "X-USER-ID": "your_user_id_here"
}

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  "https://app.go.kizen.com/api/custom-objects/{object_pk}/detail",
  {
    method: "GET",
    headers: {
      "accept": "application/json",
      "X-API-KEY": "your_api_key_here",
      "X-BUSINESS-ID": "your_business_id_here",
      "X-USER-ID": "your_user_id_here"
    }
  }
);

const data = await response.json();
console.log(data);
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### Receive and understand the response

A successful request returns HTTP **200** with a JSON body containing the full schema definition of the <code class="expression">space.vars.object</code>. Key fields in the response include:

| Field              | Description                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`               | The UUID of the <code class="expression">space.vars.object</code>                                                                                            |
| `object_name`      | The display name of the <code class="expression">space.vars.object</code>                                                                                    |
| `object_type`      | Either `pipeline` or `standard`                                                                                                                              |
| `fields`           | An array of all field definitions on the <code class="expression">space.vars.object</code>, including field type, display name, and access rules             |
| `field_categories` | The category groupings fields are organized into                                                                                                             |
| `pipeline`         | Pipeline configuration, including stages, if the <code class="expression">space.vars.object</code> has a <code class="expression">space.vars.workflow</code> |
| `access`           | Whether the current user can view, edit, or remove this <code class="expression">space.vars.object</code>                                                    |

**Example Responses**

{% tabs %}
{% tab title="cURL" %}
cURL prints the raw JSON response directly to the terminal:

```
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object_type": "pipeline",
  "object_name": "Contacts",
  "entity_name": "Contact",
  "is_custom": false,
  "allow_relations": true,
  "fields": [...],
  "field_categories": [...],
  "pipeline": {...},
  "access": {
    "view": true,
    "edit": true,
    "remove": false
  }
}
```

{% endtab %}

{% tab title="Python" %}
`response.json()` parses the JSON into a Python dictionary and `print()` outputs it to the console:

```python
{'id': '123e4567-e89b-12d3-a456-426614174000', 'object_type': 'pipeline', 'object_name': 'Contacts', 'entity_name': 'Contact', 'is_custom': False, 'allow_relations': True, 'fields': [...], 'field_categories': [...], 'pipeline': {...}, 'access': {'view': True, 'edit': True, 'remove': False}}
```

{% endtab %}

{% tab title="JavaScript" %}
`console.log()` outputs the parsed JSON object to the browser or Node.js console:

```javascript
{
  id: '123e4567-e89b-12d3-a456-426614174000',
  object_type: 'pipeline',
  object_name: 'Contacts',
  entity_name: 'Contact',
  is_custom: false,
  allow_relations: true,
  fields: [...],
  field_categories: [...],
  pipeline: {...},
  access: { view: true, edit: true, remove: false }
}
```

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

***

## Troubleshooting

If your request does not return a successful `200` response, the HTTP status code in the response will help you identify what went wrong. The most common errors when making your first API call are misconfigured credentials or an incorrect <code class="expression">space.vars.object</code> ID. Use the table below to diagnose and resolve the issue.

<table><thead><tr><th>Status Code</th><th width="249">Likely Cause</th><th>Resolution</th></tr></thead><tbody><tr><td><code>401 Unauthorized</code></td><td>Missing or invalid <code>X-API-KEY</code>, wrong <code>business_id</code> or <code>user_id</code></td><td>Verify your API Key is correct and has not been deleted, and that you have the correct business and user id.</td></tr><tr><td><code>403 Forbidden</code></td><td>User does not have permission to access the <code class="expression">space.vars.object</code></td><td>Check the API user's permission group in <code class="expression">space.vars.Kizen_company_name</code></td></tr><tr><td><code>404 Not Found</code></td><td>The <code>object_pk</code> does not exist or the URL is incorrect</td><td>Confirm the <code class="expression">space.vars.object</code> UUID and that you are using the correct environment URL</td></tr></tbody></table>

If you continue to experience issues after checking the above, contact your <code class="expression">space.vars.Kizen\_company\_name</code> administrator to verify your credentials and permission group are correctly configured. For additional support, visit our [Where to Find Help](https://developer.kizen.com/docs/readme/where-to-find-help) page.

***

## What's Next

With your first API call complete, you have everything you need to start exploring the rest of the <code class="expression">space.vars.Kizen\_company\_name</code> API. Some good next steps include:

* Query, create, or update <code class="expression">space.vars.entities</code> for the <code class="expression">space.vars.object</code> using the <code class="expression">space.vars.entities</code> APIs
* Use the field identifiers returned in the response to construct <code class="expression">space.vars.entity</code> payloads
* Explore the full API Reference at [developer.kizen.com/api](https://developer.kizen.com/api)
* Test endpoints interactively using the Swagger docs at [app.go.kizen.com/api/docs/public/swagger](https://app.go.kizen.com/api/docs/public/swagger)

<details>

<summary>Related Topics</summary>

* [Environments](https://developer.kizen.com/docs/developers/environments)
* [Authentication](https://developer.kizen.com/docs/developers/authentication)
* [Build With APIs](https://developer.kizen.com/docs/developers/building-with-apis)
* [Generate API Credentials](https://developer.kizen.com/docs/developers/building-with-apis/generating-api-credentials)

</details>