{"openapi":"3.1.0","info":{"title":"Fabiana API","version":"1.0.0","description":"Send contacts and events from your own product to Fabiana. Events and custom field changes can start automations and email sequences."},"security":[{"apiKey":[]}],"paths":{"/v1/contacts":{"get":{"operationId":"listContacts","summary":"List contacts","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"From the previous page"}],"responses":{"200":{"description":"One page of contacts","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"nextCursor":{"type":"string"}}}}}},"400":{"description":"The request is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key's role does not allow this, or the plan has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this organization (300 a minute by default)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createContact","summary":"Create a contact, or return the existing one with the same email or phone","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","description":"Who the contact is. At least email or phone is required; an existing contact with either is reused.","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"International format, e.g. +34612345678"},"name":{"type":"string","maxLength":200},"emailOptIn":{"type":"boolean","description":"Whether the person agreed to receive marketing email. Sequences and automated emails only reach contacts who agreed or are customers."}}},{"type":"object","properties":{"stage":{"type":"string","enum":["new_lead","qualified","quoted","booked","returning","vip","lost"]},"tags":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"},"properties":{"type":"object","description":"Up to 50 flat values (string, number or boolean). Keys use letters, digits and _. Saved on the contact as custom fields.","additionalProperties":{"oneOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"}]},"example":{"plan":"pro","seats":3}}}}]}}}},"responses":{"200":{"description":"The contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"The request is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key's role does not allow this, or the plan has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this organization (300 a minute by default)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts/{id}":{"get":{"operationId":"getContact","summary":"Get a contact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"The request is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key's role does not allow this, or the plan has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such contact in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this organization (300 a minute by default)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateContact","summary":"Update a contact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"tags":{"type":"array","items":{"type":"string"},"description":"Replaces the tags"},"stage":{"type":"string"},"emailOptIn":{"type":"boolean"},"company":{"type":"string"},"jobTitle":{"type":"string"},"customFields":{"type":"object","description":"Replaces all custom fields; send the full set. To merge, use POST /v1/events."}}}}}},"responses":{"200":{"description":"The updated contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"The request is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key's role does not allow this, or the plan has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such contact in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this organization (300 a minute by default)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events":{"post":{"operationId":"trackEvent","summary":"Record something a contact did in your product","description":"Creates the contact if needed, merges the properties into its custom fields, adds the event to its timeline, stops sequences set to end on this event, and runs automations listening for it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","contact"],"properties":{"event":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,100}$","example":"signed_up"},"contact":{"type":"object","description":"Who the contact is. At least email or phone is required; an existing contact with either is reused.","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"International format, e.g. +34612345678"},"name":{"type":"string","maxLength":200},"emailOptIn":{"type":"boolean","description":"Whether the person agreed to receive marketing email. Sequences and automated emails only reach contacts who agreed or are customers."}}},"properties":{"type":"object","description":"Up to 50 flat values (string, number or boolean). Keys use letters, digits and _. Saved on the contact as custom fields.","additionalProperties":{"oneOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"}]},"example":{"plan":"pro","seats":3}}}}}}},"responses":{"200":{"description":"The event was recorded","content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string"},"created":{"type":"boolean","description":"Whether this call created the contact"}}}}}},"400":{"description":"The request is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key's role does not allow this, or the plan has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this organization (300 a minute by default)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An organization API key from Settings > API keys, sent as \"Authorization: Bearer fab.<...>\"."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string"}}},"Contact":{"type":"object","properties":{"contactId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"stage":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"customFields":{"type":"object"},"emailOptIn":{"type":"boolean"},"leadSource":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}