API Reference / Identities REST

Actions

Creates a new identity (user or organization).

POST/identities

Create Identity

Headers

Authorizationstringrequired

Bearer access token returned by the authentication endpoint.

x-api-keystringrequired

The API key used for authentication when making requests to the API Gateway.

conomyhq-api-versionstring

API version selector for Conomy endpoints. Use 24-04-2025 for the current version.

User-Agentstringrequired

Identifies the application making the request.

Request body

typestring

USERORGANIZATION

namestringrequired

The name of the entity (for users) or the official name (for organizations).

nicknamestring

An alternative or preferred name for the entity.

emailstringrequired

The email address associated with the entity.

phonestringrequired

he phone number linked to the entity. Include +(phone country code)

documentNumberstringrequired

The document number associated with the entity for identification purposes.

documentTypestringrequired

The type of document (e.g., PASSPORT, NATIONAL_ID, RUT, CURP, etc).

idvstringrequired

Identity verification reference

securityOptionsobject

twoFactorAuthboolean

Indicates whether two-factor authentication is enabled

signTrxboolean

Determines if the entity is required to sign transactions

signAccountsOperationsboolean

Determines if the entity is required to sign account-related operations

accessControlobjectshow 1 properties

Dashboard access control assigned to the identity

countrystring

Country of operations for the entity, specified using the ISO 3166-1 alpha-3 standard (e.g., CHL, USA, MEX). Go to the countries page for the complete list of supported values.

childrenobject[]

A list of related entities (e.g., subsidiaries for organizations or dependent users

idstringrequired

ID

namestringrequired

emailstringrequired

externalIdstring

External reference ID (client purpose).

lastnamestring

The last name of the user (if applicable).

bankAccountobject

A reference to the associated bank account

accountNumberstringrequired

The bank account number.

nicknamestring

A friendly name assigned to the bank account.

bankstringrequired

The name of the bank where the account is held.

currencystringrequired

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

typeAccountstring

The type of bank account. CHECKING_ACOUNT, SAVINGS

accountHolderstringrequired

The full name of the account holder.

accountHolderDnistringrequired

The national identification number or tax ID of the account holder.

countrystringrequired

Country of operations for the entity, specified using the ISO 3166-1 alpha-3 standard (e.g., CHL, USA, MEX). Go to the countries page for the complete list of supported values.

rulesobject

Custom rules or policies applicable to the entity.

Responses

200Request processed successfully.

idstring

Unique identifier for the internal service.

typestring

USERRepresents an individual with personal identifying information.

ORGANIZATIONA legal entity such as a company, institution, or other juridical person

namestring

The name of the entity (for users) or the official name (for organizations).

nicknamestring

An alternative or preferred name for the entity.

emailstringemail

The email address associated with the entity.

phonestring

the phone number linked to the entity. Include +(phone country code)

documentNumberstring

The document number associated with the entity for identification purposes.

documentTypestring

Documeny type of the entity (e.g., RUT, CURP, CURL). Go to the Supported Identity document types page for the complete list of supported values.

idvstring

Identity verification reference

securityOptionsobjectshow 4 properties

countrystring

Country of operations for the entity, specified using the ISO 3166-1 alpha-3 standard (e.g., CHL, USA, MEX). Go to the countries page for the complete list of supported values.

childrenobject[]show items

A list of related entities (e.g., subsidiaries for organizations or dependent users

statusstring

The current status of the entity. PENDING, PENDING_EMAIL_VALIDATION, PENDING_PHONE_VALIDATION, SCREENING, ACTIVE

externalIdstring

External reference ID (client purpose).

lastnamestring

The last name of the user (if applicable).

bankAccountobjectshow 12 properties

Schema representing a bank account, including essential details about the account holder and financial institution.

rulesobjectshow 0 properties

Custom rules or policies applicable to the entity.

genderstring

Gender information (if applicable

kycobjectshow 0 properties

Information related to Know Your Customer (KYC) compliance

watchListobjectshow 0 properties

Watchlist information for compliance or fraud detection.

extendedDatastring[]

Additional data.

createdAtstringdate-time

Creation date UTC format.

updatedAtstringdate-time

Time of last update made to the entity, UTC format.

addressobjectshow 8 properties

The entity’s address information.

400Invalid request parameters or payload.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

500Unexpected internal server error.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

Request

HTTPcurlTypeScriptPythonGoRust

POST /sandbox/identities HTTP/1.1
Host: api.conomyhq.com
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {YOUR_API_KEY}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Content-Type: application/json

{
  "type": "USER",
  "name": "Juan Pérez",
  "nickname": "juanp",
  "email": "juan.perez-3@example.com",
  "phone": "+56912345674",
  "documentType": "RUT",
  "documentNumber": "123125",
  "status": "ACTIVE",
  "idv": "iv-23123",
  "country": "CHL",
  "securityOptions": {
    "twoFactorEnabled": false,
    "accessControl": {
      "scopes": [
        {
          "resource": "IDENTITY",
          "reference": "6808d26af21dc6b97c1cc12a",
          "permissions": [
            "account:write",
            "account:read"
          ]
        }
      ]
    }
  },
  "children": []
}

curl -X POST \
  'https://api.conomyhq.com/sandbox/identities' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "USER",
    "name": "Juan Pérez",
    "nickname": "juanp",
    "email": "juan.perez-3@example.com",
    "phone": "+56912345674",
    "documentType": "RUT",
    "documentNumber": "123125",
    "status": "ACTIVE",
    "idv": "iv-23123",
    "country": "CHL",
    "securityOptions": {
      "twoFactorEnabled": false,
      "accessControl": {
        "scopes": [
          {
            "resource": "IDENTITY",
            "reference": "6808d26af21dc6b97c1cc12a",
            "permissions": [
              "account:write",
              "account:read"
            ]
          }
        ]
      }
    },
    "children": []
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/identities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "USER",
    "name": "Juan Pérez",
    "nickname": "juanp",
    "email": "juan.perez-3@example.com",
    "phone": "+56912345674",
    "documentType": "RUT",
    "documentNumber": "123125",
    "status": "ACTIVE",
    "idv": "iv-23123",
    "country": "CHL",
    "securityOptions": {
      "twoFactorEnabled": false,
      "accessControl": {
        "scopes": [
          {
            "resource": "IDENTITY",
            "reference": "6808d26af21dc6b97c1cc12a",
            "permissions": [
              "account:write",
              "account:read"
            ]
          }
        ]
      }
    },
    "children": []
  }),
});

const data = await response.json();

import requests

payload = {
    "type": "USER",
    "name": "Juan Pérez",
    "nickname": "juanp",
    "email": "juan.perez-3@example.com",
    "phone": "+56912345674",
    "documentType": "RUT",
    "documentNumber": "123125",
    "status": "ACTIVE",
    "idv": "iv-23123",
    "country": "CHL",
    "securityOptions": {
        "twoFactorEnabled": false,
        "accessControl": {
            "scopes": [
                {
                    "resource": "IDENTITY",
                    "reference": "6808d26af21dc6b97c1cc12a",
                    "permissions": [
                        "account:write",
                        "account:read"
                    ]
                }
            ]
        }
    },
    "children": []
}

response = requests.post(
    'https://api.conomyhq.com/sandbox/identities',
    headers={
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    },
    json=payload
)

data = response.json()

package main

import (
	"encoding/json"
	"net/http"
	"bytes"
)

func main() {
	payload, _ := json.Marshal(	{
	  "type": "USER",
	  "name": "Juan Pérez",
	  "nickname": "juanp",
	  "email": "juan.perez-3@example.com",
	  "phone": "+56912345674",
	  "documentType": "RUT",
	  "documentNumber": "123125",
	  "status": "ACTIVE",
	  "idv": "iv-23123",
	  "country": "CHL",
	  "securityOptions": {
	    "twoFactorEnabled": false,
	    "accessControl": {
	      "scopes": [
	        {
	          "resource": "IDENTITY",
	          "reference": "6808d26af21dc6b97c1cc12a",
	          "permissions": [
	            "account:write",
	            "account:read"
	          ]
	        }
	      ]
	    }
	  },
	  "children": []
	})
	body := bytes.NewBuffer(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/identities", body)
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	var data map[string]any
	json.NewDecoder(resp.Body).Decode(&data)
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let resp = client
        .post("https://api.conomyhq.com/sandbox/identities")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .json(&json!({
        "type": "USER",
        "name": "Juan Pérez",
        "nickname": "juanp",
        "email": "juan.perez-3@example.com",
        "phone": "+56912345674",
        "documentType": "RUT",
        "documentNumber": "123125",
        "status": "ACTIVE",
        "idv": "iv-23123",
        "country": "CHL",
        "securityOptions": {
                "twoFactorEnabled": false,
                "accessControl": {
                        "scopes": [
                                {
                                        "resource": "IDENTITY",
                                        "reference": "6808d26af21dc6b97c1cc12a",
                                        "permissions": [
                                                "account:write",
                                                "account:read"
                                        ]
                                }
                        ]
                }
        },
        "children": []
}))
        .send()
        .await?;

    let data: serde_json::Value = resp.json().await?;
    Ok(())
}

Response

200 400 401 403 404 422 500

{
  "id": "string",
  "type": "USER",
  "name": "string",
  "nickname": "string",
  "email": "user@example.com",
  "phone": "string",
  "documentNumber": "string",
  "documentType": "string",
  "idv": "string",
  "securityOptions": {}
}

{
  "error": {
    "type": "bad_request",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "unauthorized",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "forbidden",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "not_found",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "validation_error",
    "info": {
      "field": "string",
      "message": "string"
    }
  },
  "message": null
}

{
  "error": {
    "type": "internal_error",
    "info": null
  },
  "message": null
}