Create Your First API Call

Audience: Developers

Purpose: Provides step-by-step instructions for making an authenticated request to the Kizen API using an API Key, Business ID, and User ID, using the Retrieve Object Details by ID endpoint as a working example.

Overview

Now that you have your API credentials, you are ready to make your first authenticated request to the Kizen 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 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 Object in your Kizen platform. If you have not yet created one, see Create Your First Object
• Record details in your Object. If you have not yet created any, see Create Your First Record
• The Object ID of the Object you want to retrieve — this is a UUID found in your Kizen Object 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 endpoint as the example call. This endpoint returns the full schema definition for a single Object 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 Object you want to retrieve.

---

Create Your First API Call

1

Assemble your request headers

Every Kizen API call requires the same three headers. Pull these from the credentials you generated in Generate 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

2

Make the request

Choose your preferred tool below. Replace the placeholder values with your actual credentials and the Object's entity_id, which you can find in the General Settings page of the Object when viewing it in edit mode.

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"

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())

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);

3

Receive and understand the response

A successful request returns HTTP 200 with a JSON body containing the full schema definition of the Object. Key fields in the response include:

Field	Description
id	The UUID of the Object
object_name	The display name of the Object
object_type	Either pipeline or standard
fields	An array of all field definitions on the Object, including field type, display name, and access rules
field_categories	The category groupings fields are organized into
pipeline	Pipeline configuration, including stages, if the Object has a Workflow
access	Whether the current user can view, edit, or remove this Object

Example Responses

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
  }
}

Python

response.json() parses the JSON into a Python dictionary and print() outputs it to the console:

{'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}}

JavaScript

console.log() outputs the parsed JSON object to the browser or Node.js console:

{
  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 }
}

---

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 Object ID. Use the table below to diagnose and resolve the issue.

Status Code	Likely Cause	Resolution
401 Unauthorized	Missing or invalid X-API-KEY, wrong business_id or user_id	Verify your API Key is correct and has not been deleted, and that you have the correct business and user id.
403 Forbidden	User does not have permission to access the Object	Check the API user's permission group in Kizen
404 Not Found	The object_pk does not exist or the URL is incorrect	Confirm the Object UUID and that you are using the correct environment URL

If you continue to experience issues after checking the above, contact your Kizen administrator to verify your credentials and permission group are correctly configured. For additional support, visit our 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 Kizen API. Some good next steps include:

• Query, create, or update Records for the Object using the Records APIs
• Use the field identifiers returned in the response to construct Record payloads
• Explore the full API Reference at developer.kizen.com/api
• Test endpoints interactively using the Swagger docs at app.go.kizen.com/api/docs/public/swagger

Related Topics

• Environments
• Authentication
• Build With APIs
• Generate API Credentials