Getting started/Jestiyon - Public API

Getting started

Jestiyon - Public API

The public API for external companies that integrate with Jestiyon. Use api.jestiyon.com for production and api-sandbox.jestiyon.com for testing.

Base URL

BASE URL

https://api-sandbox.jestiyon.com

Environment

Base URL

Production

https://api.jestiyon.com

Sandbox

https://api-sandbox.jestiyon.com

Getting started

Authentication

Requests are authenticated with an API key sent in a request header.

API key

Şirketinize verilen API anahtarı. 'X-Api-Key' başlığında gönderin. Kimlik doğrulama bu önizleme sürümünde henüz zorunlu değildir.

AUTHORIZATION

curl https://api-sandbox.jestiyon.com/api/v1/companies \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Getting started

Form a Turkish company in four steps: create the company, submit setup data and documents, then poll its status until formation completes.

1. Pick a firm type

Call GET /api/v1/reference/firm-types and note the firmTypeId you need — 1 for Şahıs İşletmesi (sole proprietorship), 2 for Limited Şirket. You send this exact value as firmTypeId when creating the company.

2. Create the company

POST the admin user and title to /api/v1/companies. The response returns the companyId you use for every later call, with taxNumber and taxOffice still null until the tax office is assigned.

CREATE COMPANY

curl -X POST https://api-sandbox.jestiyon.com/api/v1/companies \
  -H "X-Api-Key: YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Örnek Yazılım Ltd. Şti.",
    "firmTypeId": 2,
    "firstName": "Ayşe",
    "lastName": "Yılmaz",
    "email": "ayse.yilmaz@ornek.com",
    "mobilePrefix": "+90",
    "mobilePhone": "5321234567"
  }'

3. Submit setup

POST /api/v1/companies/{companyId}/setup with the formation data and the required document files in one multipart request. See the Companies section for the full field list per firm type. Attach any remaining documents with the documents endpoint using the numeric documentType id from /reference/document-types.

4. Poll the status

Poll GET /api/v1/companies/{companyId}/status (or subscribe to the company.status_changed webhook) until status is completed. If documents are rejected the response lists each rejection with how to fix it.

POLL STATUS

curl https://api-sandbox.jestiyon.com/api/v1/companies/1/status \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Status values

GET /api/v1/reference/statuses is the single source of truth for every status value the API and webhooks return. Optional fields you have not been assigned yet — like taxNumber — are returned as null, never omitted.

Core resources

Companies

Operations in the Companies group.

GET/api/v1/companies

List companies

Returns every company created under your partner account, with its title, tax details and current formation status.

Parameters

ReturnsA successful response.

companyIdinteger

titlestring

taxNumberstring, nullable

taxOfficestring, nullable

statusstring

curl https://api-sandbox.jestiyon.com/api/v1/companies \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

[
  {
    "companyId": 1,
    "title": "Örnek Yazılım Ltd. Şti.",
    "taxNumber": null,
    "taxOffice": null,
    "status": "pending_document_review"
  }
]

Try itapi-sandbox.jestiyon.com

Simulated response, no data is written.

POST/api/v1/companies

Create company

Creates a Turkish company shell and its admin user on behalf of your partner account. Formation data is submitted separately through the setup endpoint.

Parameters

titlestringrequired

firmTypeIdinteger · int32required

Company type (from GET /api/v1/reference/firm-types). Determines the setup requirements.

firstNamestringrequired

lastNamestringrequired

emailstring · emailrequired

mobilePrefixstringoptional

mobilePhonestringrequired

ReturnsA successful response.

companyIdinteger

titlestring

taxNumberstring, nullable

taxOfficestring, nullable

statusstring

curl -X POST https://api-sandbox.jestiyon.com/api/v1/companies \
  -H "X-Api-Key: YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "title": "Örnek Yazılım Ltd. Şti.", \
    "firmTypeId": 2, \
    "firstName": "Ayşe", \
    "lastName": "Yılmaz", \
    "email": "ayse.yilmaz@ornek.com", \
    "mobilePrefix": "+90", \
    "mobilePhone": "5321234567" \
  }'

Example response200

{
  "companyId": 1,
  "title": "Örnek Yazılım Ltd. Şti.",
  "taxNumber": null,
  "taxOffice": null,
  "status": "pending_document_review"
}

Example error400

{
  "error": {
    "code": "parameter_missing",
    "message": "Missing required parameter: firmTypeId.",
    "param": "firmTypeId",
    "request_id": "req_8Vd1pQ2mZ0"
  }
}

Try itapi-sandbox.jestiyon.com

title*

firmTypeId*

firstName*

lastName*

email*

mobilePrefix

mobilePhone*

Simulated response, no data is written.

GET/api/v1/companies/{id}

Get company

Returns a single partner-owned company by its id.

Parameters

idinteger · int32required

ReturnsA successful response.

companyIdinteger

titlestring

taxNumberstring, nullable

taxOfficestring, nullable

statusstring

curl https://api-sandbox.jestiyon.com/api/v1/companies/1 \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

{
  "companyId": 1,
  "title": "Örnek Yazılım Ltd. Şti.",
  "taxNumber": null,
  "taxOffice": null,
  "status": "pending_document_review"
}

Example error404

{
  "error": {
    "code": "not_found",
    "message": "No company found with id 999.",
    "request_id": "req_7Kp2mNq0Za"
  }
}

Try itapi-sandbox.jestiyon.com

id*

Simulated response, no data is written.

GET/api/v1/companies/{id}/status

Company status

Returns a company's current formation status, whether setup has been submitted, and any outstanding document rejections.

Parameters

idinteger · int32required

ReturnsA successful response.

companyIdinteger

statusstring

isSetupSubmittedboolean

rejectionsstring, nullable

curl https://api-sandbox.jestiyon.com/api/v1/companies/1/status \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

{
  "companyId": 1,
  "status": "pending_document_review",
  "isSetupSubmitted": true,
  "rejections": null
}

Try itapi-sandbox.jestiyon.com

id*

Simulated response, no data is written.

POST/api/v1/companies/{id}/setup

Submit setup

Submits formation data and documents in a single multipart request: a JSON data field (owner, partners, managers, capital, activity scope) plus owner and manager document files.

Parameters

idinteger · int32required

ReturnsA successful response.

companyIdinteger

statusstring

detailsarray

Each item

detailIdinteger

typestring

namestring

curl -X POST https://api-sandbox.jestiyon.com/api/v1/companies/1/setup \
  -H "X-Api-Key: YOUR_SANDBOX_KEY" \
  -F "name=Ayşe Yılmaz" \
  -F "identityNo=12345678901" \
  -F "isForeignIdentity=false" \
  -F "birthDate=1990-05-14T00:00:00Z" \
  -F "birthPlace=İstanbul" \
  -F "cityId=34" \
  -F "townId=1234" \
  -F "address=Bağdat Cad. No:1, Kadıköy" \
  -F "addressCountry=TR" \
  -F "email=ayse.yilmaz@ornek.com" \
  -F "phonePrefix=+90" \
  -F "phone=5321234567" \
  -F "isVehicleOperation=false" \
  -F "ownerIdentityFront=@/path/to/ownerIdentityFront" \
  -F "ownerIdentityBack=@/path/to/ownerIdentityBack" \
  -F "ownerAddressStatement=@/path/to/ownerAddressStatement" \
  -F "ownerPassport=@/path/to/ownerPassport" \
  -F "ownerResidency=@/path/to/ownerResidency" \
  -F "totalCapital=50000" \
  -F "shareCount=100" \
  -F "shareNominalValue=500" \
  -F "currency=TRY" \
  -F "activityScope=Yazılım geliştirme ve danışmanlık" \
  -F "managerIdentityFronts=@/path/to/managerIdentityFronts" \
  -F "managerIdentityBacks=@/path/to/managerIdentityBacks" \
  -F "managerResidencies=@/path/to/managerResidencies" \
  # + partner*/manager* array parts: repeat -F once per value (see Parameters)

Example response200

{
  "companyId": 1,
  "status": "pending_document_review",
  "details": [
    {
      "detailId": 11,
      "type": "partner",
      "name": "Mehmet Demir"
    },
    {
      "detailId": 12,
      "type": "manager",
      "name": "Ayşe Yılmaz"
    }
  ]
}

POST/api/v1/companies/{id}/documents

Upload document

Uploads a single formation document into an owner or partner/manager slot.

Parameters

idinteger · int32required

documentTypestringrequired

The document slot to fill. The owner supports every slot; a partner/manager supports identity and residency.

detailIdinteger · int32optional

Target partner/manager id (from the setup response). Omit to attach to the owner.

filefilerequired

ReturnsA successful response.

documentIdinteger

documentTypestring

detailIdstring, nullable

fileNamestring

curl -X POST https://api-sandbox.jestiyon.com/api/v1/companies/1/documents \
  -H "X-Api-Key: YOUR_SANDBOX_KEY" \
  -F "documentType=1" \
  -F "file=@/path/to/file"

Example response200

{
  "documentId": 5001,
  "documentType": "IdentityFront",
  "detailId": null,
  "fileName": "identity-front.jpg"
}

Try itapi-sandbox.jestiyon.com

id*

documentType*

detailId

Simulated response, no data is written.

Core resources

Me

Operations in the Me group.

GET/api/v1/me

Current partner

Echoes the authenticated partner's id, name, tier and the environment of the key used.

Parameters

ReturnsThe authenticated partner.

partnerIdinteger

namestring

tierstring

environmentstring

curl https://api-sandbox.jestiyon.com/api/v1/me \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

{
  "partnerId": 1,
  "name": "Örnek Entegrasyon A.Ş.",
  "tier": "standard",
  "environment": "sandbox"
}

Try itapi-sandbox.jestiyon.com

Simulated response, no data is written.

Core resources

Ping

Operations in the Ping group.

GET/api/v1/ping

Ping

Returns a lightweight liveness response. Requires no authentication and is safe to call for uptime checks.

Parameters

ReturnsThe API is reachable.

statusstring

versionstring

environmentstring

serverTimeUtcstring

curl https://api-sandbox.jestiyon.com/api/v1/ping

Example response200

{
  "status": "ok",
  "version": "1.0",
  "environment": "sandbox",
  "serverTimeUtc": "2026-08-12T09:30:00Z"
}

Try itapi-sandbox.jestiyon.com

Simulated response, no data is written.

Core resources

Reference

Operations in the Reference group.

GET/api/v1/reference/firm-types

Firm types

Returns the available Turkey firm types.

Parameters

ReturnsA successful response.

firmTypeIdinteger

namestring

descriptionstring

countryIdinteger

requiresCapitalboolean

curl https://api-sandbox.jestiyon.com/api/v1/reference/firm-types \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

[
  {
    "firmTypeId": 1,
    "name": "Şahıs İşletmesi",
    "description": "Tek kişilik işletme",
    "countryId": 1,
    "requiresCapital": false
  },
  {
    "firmTypeId": 2,
    "name": "Limited Şirket",
    "description": "Sermaye şirketi (Ltd. Şti.)",
    "countryId": 1,
    "requiresCapital": true
  }
]

Try itapi-sandbox.jestiyon.com

Simulated response, no data is written.

GET/api/v1/reference/currencies

Currencies

Returns the available currencies.

Parameters

ReturnsA successful response.

idinteger

namestring

curl https://api-sandbox.jestiyon.com/api/v1/reference/currencies \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

[
  {
    "id": 1,
    "name": "TRY"
  },
  {
    "id": 2,
    "name": "USD"
  }
]

Try itapi-sandbox.jestiyon.com

Simulated response, no data is written.

GET/api/v1/reference/cities

Cities

Returns the list of Turkey cities.

Parameters

ReturnsA successful response.

idinteger

namestring

curl https://api-sandbox.jestiyon.com/api/v1/reference/cities \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

[
  {
    "id": 34,
    "name": "İstanbul"
  },
  {
    "id": 6,
    "name": "Ankara"
  }
]

Try itapi-sandbox.jestiyon.com

Simulated response, no data is written.

GET/api/v1/reference/towns

Towns

Returns the towns (İlçe) of a city.

Parameters

cityIdinteger · int32required

The city id (from /reference/cities).

ReturnsA successful response.

idinteger

namestring

curl https://api-sandbox.jestiyon.com/api/v1/reference/towns?cityId=1 \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

[
  {
    "id": 1234,
    "name": "Kadıköy"
  },
  {
    "id": 1235,
    "name": "Beşiktaş"
  }
]

Try itapi-sandbox.jestiyon.com

cityId*

Simulated response, no data is written.

GET/api/v1/reference/document-types

Document types

Returns the document categories accepted for formation uploads.

Parameters

ReturnsA successful response.

idinteger

namestring

curl https://api-sandbox.jestiyon.com/api/v1/reference/document-types \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

[
  {
    "id": 1,
    "name": "IdentityFront"
  },
  {
    "id": 2,
    "name": "IdentityBack"
  },
  {
    "id": 3,
    "name": "AddressStatement"
  },
  {
    "id": 4,
    "name": "Passport"
  },
  {
    "id": 5,
    "name": "Residency"
  }
]

Try itapi-sandbox.jestiyon.com

Simulated response, no data is written.

GET/api/v1/reference/statuses

Statuses

Returns the set of formation status values the API can return.

Parameters

ReturnsA successful response.

curl https://api-sandbox.jestiyon.com/api/v1/reference/statuses \
  -H "X-Api-Key: YOUR_SANDBOX_KEY"

Example response200

[
  "pending_document_review",
  "documents_approved",
  "e_signature_pending",
  "e_invoice_setup",
  "completed",
  "rejected"
]

Try itapi-sandbox.jestiyon.com

Simulated response, no data is written.

Events

Webhooks

Jestiyon posts signed events to your webhook URL as company formation status changes.

Jestiyon POSTs company.status_changed events to your configured webhook URL on every formation status change. The body matches the CompanyStatusChangedWebhook schema and is signed with HMAC-SHA256 (hex) over the raw body in the X-Signature header — verify it with your webhook secret. Return 2xx to acknowledge; non-2xx or timeouts are retried with backoff.

Registering a webhook

Webhook delivery is configured per partner account. Contact the Jestiyon integration team to register your callback URL and receive your signing secret — there is no self-serve endpoint yet.

Status values

Each company.status_changed event carries one of the following status values. All of them are triggered internally by Jestiyon.

Status value

When it fires

documents_approved

The financial advisor approved the uploaded documents.

e_signature_pending

Setup completed and the tax office was assigned.

e_invoice_setup

The e-signature process is complete and the e-invoice integrator setup has started.

completed

The company is fully formed (done).

rejected

Documents were rejected — the payload includes a rejections[] array (part, reason and how to fix).

Example payload

WEBHOOK PAYLOAD

{
  "event": "company.status_changed",
  "companyId": 1,
  "status": "documents_approved",
  "occurredAtUtc": "2026-08-12T09:30:00Z"
}

Resources

Errors

Every error uses the same JSON envelope. Read error.code for branching and error.message for a human-readable reason.

ERROR ENVELOPE

{
  "error": {
    "code": "parameter_missing",
    "message": "Missing required parameter: firmTypeId.",
    "param": "firmTypeId",
    "request_id": "req_8Vd1pQ2mZ0"
  }
}

Status codes

Code

Meaning

400

A parameter is missing or invalid (see error.param).

401

The API key is missing or invalid.

404

No resource with that id under your account.

429

Rate limit exceeded — see Retry-After.

Rate limits

When you exceed your tier's rate limit the API returns 429 with a Retry-After header (in seconds). Wait that long before retrying; retrying sooner keeps failing.

Null vs. omitted

Optional fields are always present with a null value when unset — they are never dropped from the response. Check for null (resp.taxNumber === null), not for an absent key.

Resources

Changelog

Notable changes to the public API.

v1.0 — August 2026

1Initial public API: Companies (create, get, list, setup, documents, status), Me, Ping and the Reference lookups.

2Webhooks: Jestiyon POSTs signed company.status_changed events (HMAC-SHA256) as formation status changes.

3External-owned models use camelCase throughout (e.g. firmTypeId, name); the internal ds/id naming is not exposed.

Resources

Support

Get help from the Jestiyon integration team.

contact

Jestiyon Entegrasyon Ekibi

Reach out for API access, sandbox keys and integration questions.

integrations@jestiyon.com

website

Website

Product information and company details.

www.jestiyon.com

Open a ticket

Routed to the Jestiyon integration team.

Contact Name

Contact Email

Subject