Create a vendor

POSThttps://rebaar.in/api/v1/vendors/createView as Markdown

Adds a vendor. Optional `pincode`, `stateCode` and `district`: the PIN fills the state and district when they are not sent, and a state the PIN rules out is 400 with `field: "pincode"`. One vendor per GSTIN: a `gstin` another vendor of your company already has is 409 `gstin_taken` with `field: "gstin"` and `vendor: { id, name }` naming the vendor to use instead.

Headers

Header	Value
Authorizationrequired	`Bearer ck_live_…` — your API key from Settings → API keys
Content-Typerequired	`application/json`

Request body

Field	Type	Description
namerequired	string	at most 200 characters
category	string	at most 80 characters
city	string	at most 80 characters
pincode	string	6-digit PIN code. The server fills stateCode and district from it when they are not sent.pattern ^[1-9][0-9]{5}$
district	string	at most 80 characters
stateCode	string	2-digit GST state code, e.g. "29" (Karnataka). 400 with field "pincode" when the PIN is not in that state.pattern ^[0-9]{2}$
gstin	string	pattern ^[0-9A-Z]{15}$
phone	string	at most 20 characters
email	string (email)
leadTimeDays	integer	minimum 0

Try it

This call changes data. Send runs it in your API sandbox — a practice company with sample data — with a sandbox key, never in your real company. To change real data, run the sample from your own machine with a live key. About the sandbox

Request body (JSON)

curl -X POST 'https://rebaar.in/api/v1/vendors/create' \
  -H 'Authorization: Bearer ck_live_xxxxxxxx_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Sri Lakshmi Cement Traders",
  "category": "Cement",
  "city": "Bengaluru",
  "pincode": "560058",
  "email": "[email protected]",
  "leadTimeDays": 3
}'

Sandbox key

Only sandbox keys (ck_test_…) — make one in Settings → API keys. It reaches your practice company, never your real data. 30 calls a minute.

Responses

201Created. The new vendor's id and name.

{
  "id": "b2e94f60-1d7c-4a3b-8e25-6f0c9d1a7e48",
  "name": "Sri Lakshmi Cement Traders"
}

400Validation failed. `error` is the first problem found; `field` names it when it is a location, GSTIN, email or delivery-address field.

{
  "error": "PIN 560076 is in Karnataka, not Maharashtra",
  "field": "pincode"
}

401No `Authorization: Bearer …` header was sent. Or: The key is unknown, revoked or expired — or the company cannot use it.

unauthenticated — No `Authorization: Bearer …` header was sent.

{
  "error": "unauthenticated",
  "message": "Authorization: Bearer <api_key> required"
}

invalid_token — The key is unknown, revoked or expired — or the company cannot use it.

{
  "error": "invalid_token",
  "message": "API key not recognised, revoked, or expired"
}

402With a sandbox key: the practice company already holds 10,000 vendors (`sandbox_limit`) — reset the sandbox in Settings → API keys. Or the plan / subscription does not allow the API.

sandbox_limit

{
  "error": "sandbox_limit",
  "message": "The sandbox holds at most 10,000 vendors. Reset the sandbox in Settings → API keys.",
  "resource": "vendors",
  "used": 10000,
  "limit": 10000
}

plan_required

{
  "error": "plan_required",
  "message": "API access requires the Scale plan. This workspace is on Growth.",
  "currentPlan": "growth",
  "requiredPlan": "scale"
}

access_expired

{
  "error": "access_expired",
  "reason": "payment_failed",
  "message": "Workspace does not currently have an active Scale subscription."
}

403The request came from an IP address that is not on the key's allowlist. Or: The key does not carry the scope this method needs: `read` for GET, `write` for POST, PATCH and DELETE.

ip_not_allowed — The request came from an IP address that is not on the key's allowlist.

{
  "error": "ip_not_allowed",
  "message": "Source IP 203.0.113.7 is not on the key's allowlist."
}

insufficient_scope — The key does not carry the scope this method needs: `read` for GET, `write` for POST, PATCH and DELETE.

{
  "error": "insufficient_scope",
  "message": "This API key does not have the 'write' scope.",
  "required": "write",
  "granted": [
    "read"
  ]
}

409Another vendor of your company has this GSTIN.

{
  "error": "gstin_taken",
  "field": "gstin",
  "message": "This GSTIN belongs to Sri Lakshmi Cement Traders — use that vendor.",
  "vendor": {
    "id": "b2e94f60-1d7c-4a3b-8e25-6f0c9d1a7e48",
    "name": "Sri Lakshmi Cement Traders"
  }
}

429More than 120 requests in a minute with this key (30 with a sandbox key).

rate_limited — More than 120 requests in a minute with this key (30 with a sandbox key).

{
  "error": "Too many requests. Please try again later."
}

500Something failed on our side.

internal — Something failed on our side.

{
  "error": "internal"
}

Errors

Errors every call can return

Status	Code	Meaning	What to do
401	unauthenticated	No `Authorization: Bearer …` header was sent.	Send your API key as `Authorization: Bearer ck_live_…` on every request.
401	invalid_token	The key is unknown, revoked or expired — or the company cannot use it.	Check you copied the whole key. Make a new one in Settings → API keys if it was revoked or has expired.
403	ip_not_allowed	The request came from an IP address that is not on the key's allowlist.	Call from an allowed address, or change the key's IP allowlist in Settings → API keys.
402	plan_required	The company is not on the Scale plan, which includes the API.	The Owner moves the company to Scale in Settings → Billing.
402	access_expired	The subscription is not active (trial over, payment failed, cancelled, paused, locked or closing). `reason` says which.	The Owner pays or renews in Settings → Billing; calls work again at once.
429	—	More than 120 requests in a minute with this key (30 with a sandbox key).	Wait the number of seconds in the `Retry-After` header. Every reply carries `RateLimit-Remaining`, so you can slow down before this happens.
403	insufficient_scope	The key does not carry the scope this method needs: `read` for GET, `write` for POST, PATCH and DELETE.	Make a key with the scope you need in Settings → API keys.
500	internal	Something failed on our side.	Retry with exponential backoff. If it keeps happening, email [email protected] with the time of the call.