# 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](/docs/concepts/objects/object-apis/retrieve-object-details-by-id-api.md) 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](/docs/kizen-basics/kizen-in-action/create-your-first-object-or-kizen-basics.md)
* <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](/docs/kizen-basics/kizen-in-action/create-your-first-record-or-kizen-basics.md)
* 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](/docs/concepts/objects/object-apis/retrieve-object-details-by-id-api.md) 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](/docs/developers/building-with-apis/generating-api-credentials.md):

| 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](/docs/readme/where-to-find-help.md) 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](/docs/developers/environments.md)
* [Authentication](/docs/developers/authentication.md)
* [Build With APIs](/docs/developers/building-with-apis.md)
* [Generate API Credentials](/docs/developers/building-with-apis/generating-api-credentials.md)

</details>


---

# 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://developer.kizen.com/docs/developers/building-with-apis/creating-your-first-api-call.md?ask=<question>
```

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.