{"openapi":"3.1.0","info":{"title":"XONIKA3 API","version":"1.0.0","description":"Read and change your CRM data from other systems. Create a key in XONIKA3 → Admin → Developers and send it as `Authorization: Bearer xk_live_…`. Money is in the smallest unit (cents/paise). Errors return `{ statusCode, code, message }`."},"servers":[{"url":"https://crm.xonik.com/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from Admin → Developers"}}},"paths":{"/crm/contacts":{"get":{"summary":"List contacts","description":"Needs the API key permission `crm.contact:read` (Read contacts and companies).","tags":["crm"],"parameters":[{"name":"search","in":"query","required":false,"description":"Name, email or company","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Per page (max 100)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}},"post":{"summary":"Create a contact","description":"Needs the API key permission `crm.contact:create` (Create contacts and companies).","tags":["crm"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"company_name":{"type":"string"},"title":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"owner_id":{"type":"string","format":"uuid"},"custom_fields":{"type":"object"}},"required":["first_name"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/crm/contacts/{id}":{"get":{"summary":"Get a contact","description":"Needs the API key permission `crm.contact:read` (Read contacts and companies).","tags":["crm"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}},"patch":{"summary":"Update a contact (only the fields sent)","description":"Needs the API key permission `crm.contact:update` (Update contacts and companies).","tags":["crm"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"title":{"type":"string"},"company_name":{"type":"string"},"status":{"type":"string"},"lifecycle_stage":{"type":"string"},"owner_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/crm/companies":{"get":{"summary":"List companies","description":"Needs the API key permission `crm.contact:read` (Read contacts and companies).","tags":["crm"],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}},"post":{"summary":"Create a company","description":"Needs the API key permission `crm.contact:create` (Create contacts and companies).","tags":["crm"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"},"industry":{"type":"string"},"size":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/crm/companies/{id}":{"patch":{"summary":"Update a company","description":"Needs the API key permission `crm.contact:update` (Update contacts and companies).","tags":["crm"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"},"industry":{"type":"string"},"tier":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/crm/deals":{"get":{"summary":"List deals","description":"Needs the API key permission `crm.deal:read` (Read deals, products, tasks and notes).","tags":["crm"],"parameters":[{"name":"stage","in":"query","required":false,"description":"lead, qualified, proposal, negotiation, won, lost","schema":{"type":"string"}},{"name":"owner_id","in":"query","required":false,"description":"Owner","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}},"post":{"summary":"Create a deal","description":"Needs the API key permission `crm.deal:create` (Create deals, tasks and notes).","tags":["crm"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"value_cents":{"type":"integer","description":"Amount in the smallest unit, e.g. 150000 = 1,500.00"},"currency":{"type":"string","description":"ISO code; default: the organization's"},"stage":{"type":"string"},"contact_id":{"type":"string","format":"uuid"},"company_id":{"type":"string","format":"uuid"},"owner_id":{"type":"string","format":"uuid"},"expected_close_date":{"type":"string","format":"date-time"}},"required":["title","value_cents"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/crm/deals/{id}":{"get":{"summary":"Get a deal","description":"Needs the API key permission `crm.deal:read` (Read deals, products, tasks and notes).","tags":["crm"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/crm/deals/{id}/move":{"post":{"summary":"Move a deal to another stage (lost needs loss_reason)","description":"Needs the API key permission `crm.deal:update` (Update deals and tasks).","tags":["crm"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage_key":{"type":"string","description":"A stage key of the deal's pipeline, e.g. won"},"pipeline_id":{"type":"string","format":"uuid"},"loss_reason":{"type":"string","description":"price, feature_gap, competitor, timing, …"}},"required":["stage_key"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/crm/products":{"get":{"summary":"List products","description":"Needs the API key permission `crm.deal:read` (Read deals, products, tasks and notes).","tags":["crm"],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/crm/tasks":{"get":{"summary":"List follow-ups","description":"Needs the API key permission `crm.deal:read` (Read deals, products, tasks and notes).","tags":["crm"],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}},"post":{"summary":"Create a follow-up","description":"Needs the API key permission `crm.deal:create` (Create deals, tasks and notes).","tags":["crm"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"due_date":{"type":"string","format":"date-time"},"priority":{"type":"string","description":"low, medium, high, urgent"},"contact_id":{"type":"string","format":"uuid"},"deal_id":{"type":"string","format":"uuid"},"assigned_to":{"type":"string","format":"uuid"}},"required":["title"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/crm/notes":{"post":{"summary":"Add a note to a contact or deal","description":"Needs the API key permission `crm.deal:create` (Create deals, tasks and notes).","tags":["crm"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"contact_id":{"type":"string","format":"uuid"},"deal_id":{"type":"string","format":"uuid"}},"required":["content"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/prospecting/leads":{"get":{"summary":"List leads","description":"Needs the API key permission `prospecting.lead:read` (Read leads).","tags":["prospecting"],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}},"post":{"summary":"Create a lead","description":"Needs the API key permission `prospecting.lead:create` (Create leads).","tags":["prospecting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string"},"contact_name":{"type":"string"},"email":{"type":"string"},"domain":{"type":"string"},"score":{"type":"integer","description":"0-100"}},"required":["company_name"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/support/tickets":{"get":{"summary":"List tickets","description":"Needs the API key permission `support.ticket:read` (Read tickets).","tags":["support"],"parameters":[{"name":"status","in":"query","required":false,"description":"open, pending, resolved, closed","schema":{"type":"string"}},{"name":"priority","in":"query","required":false,"description":"low, medium, high, urgent","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}},"post":{"summary":"Open a ticket","description":"Needs the API key permission `support.ticket:create` (Create tickets).","tags":["support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"description":{"type":"string"},"priority":{"type":"string"},"customer_email":{"type":"string","description":"Matched to (or added as) a contact"},"customer_id":{"type":"string","format":"uuid"}},"required":["subject","description"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/support/tickets/{id}":{"get":{"summary":"Get a ticket with its messages","description":"Needs the API key permission `support.ticket:read` (Read tickets).","tags":["support"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/support/tickets/{id}/messages":{"post":{"summary":"Add a reply or internal note","description":"Needs the API key permission `support.ticket:update` (Reply to and update tickets).","tags":["support"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"is_internal_note":{"type":"boolean"}},"required":["body"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/invoicing/invoices":{"get":{"summary":"List invoices","description":"Needs the API key permission `invoicing.invoice:read` (Read invoices and payments).","tags":["invoicing"],"parameters":[{"name":"status","in":"query","required":false,"description":"draft, issued, partially_paid, paid, credited, void","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}},"post":{"summary":"Create an invoice (issued unless status is draft)","description":"Needs the API key permission `invoicing.invoice:create` (Create invoices).","tags":["invoicing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_name":{"type":"string"},"customer_email":{"type":"string"},"customer_contact_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"status":{"type":"string","description":"draft or issued"},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"integer"},"unit_price_cents":{"type":"integer"},"tax_rate_percent":{"type":"number"}},"required":["description","quantity","unit_price_cents"]}}},"required":["items"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/invoicing/invoices/{id}":{"get":{"summary":"Get an invoice with lines, payments, credit notes and refunds","description":"Needs the API key permission `invoicing.invoice:read` (Read invoices and payments).","tags":["invoicing"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/commerce/orders":{"get":{"summary":"List orders","description":"Needs the API key permission `commerce.order:read` (Read orders).","tags":["commerce"],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}},"post":{"summary":"Create an order","description":"Needs the API key permission `commerce.order:create` (Create orders).","tags":["commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","format":"uuid"},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"integer"},"unit_price_cents":{"type":"integer"},"product_id":{"type":"string","format":"uuid"}},"required":["description","quantity","unit_price_cents"]}},"tax_rate_percent":{"type":"number"},"discount_code":{"type":"string"}},"required":["items"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}},"/commerce/orders/{id}":{"get":{"summary":"Get an order","description":"Needs the API key permission `commerce.order:read` (Read orders).","tags":["commerce"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid input (message says which field)"},"401":{"description":"Missing, invalid, expired or revoked key"},"403":{"description":"The key does not have this permission"},"404":{"description":"Not found in this organization"},"409":{"description":"A business rule refused it (code and message explain)"},"429":{"description":"Too many requests (600 a minute per key)"}}}}},"x-webhooks":{"contact.created":{"summary":"A contact is added","resource":"contact"},"contact.updated":{"summary":"A contact is changed","resource":"contact"},"deal.created":{"summary":"A deal is added","resource":"deal"},"deal.stage_changed":{"summary":"A deal moves stage","resource":"deal"},"deal.won":{"summary":"A deal is won","resource":"deal"},"deal.lost":{"summary":"A deal is lost","resource":"deal"},"lead.created":{"summary":"A lead is added","resource":"lead"},"ticket.created":{"summary":"A ticket is opened","resource":"ticket"},"ticket.resolved":{"summary":"A ticket is resolved or closed","resource":"ticket"},"invoice.issued":{"summary":"An invoice is issued","resource":"invoice"},"invoice.paid":{"summary":"An invoice is paid in full","resource":"invoice"},"invoice.overdue":{"summary":"An invoice becomes overdue","resource":"invoice"},"payment.received":{"summary":"A payment is recorded","resource":"invoice"},"order.created":{"summary":"An order is placed","resource":"order"},"order.paid":{"summary":"An order is paid","resource":"order"},"booking.created":{"summary":"A meeting is booked","resource":"booking"},"booking.cancelled":{"summary":"A meeting is cancelled","resource":"booking"},"form.submitted":{"summary":"A form is submitted","resource":"form_submission"}}}