{"openapi":"3.0.3","info":{"title":"Targeted API","version":"1.1.0","description":"Public API for users, deals, bookings, catalogs, campaigns, workflows, segments, and SMS. Authenticate with Authorization: Bearer and an API key from Settings → API keys."},"servers":[{"url":"https://targeted-nine.vercel.app"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings → API keys. Prefix is tgt_."}}},"tags":[{"name":"users"},{"name":"deals"},{"name":"bookings"},{"name":"events"},{"name":"catalogs"},{"name":"campaigns"},{"name":"workflows"},{"name":"journeys"},{"name":"segments"},{"name":"stages"},{"name":"sms"}],"paths":{"/api/v1/users":{"get":{"operationId":"users.list","summary":"List contacts in the workspace.","description":"Optional query params: stage, q (name/email/company/userId).","tags":["users"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"users":[{"id":"clx…","userId":"cust_123","name":"Maya Ortiz","email":"maya@example.com","stage":"contacted","dealValue":0}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"stage","in":"query","required":false,"description":"Pipeline stage key.","schema":{"type":"string","example":"contacted"}},{"name":"q","in":"query","required":false,"description":"Search name, email, company, or userId.","schema":{"type":"string","example":"maya"}}]},"post":{"operationId":"users.create","summary":"Create a contact (user) in the workspace.","description":"Optionally set userId as your external id. dealValue uses major units.","tags":["users"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"user":{"id":"clx…","userId":"cust_123","name":"Maya Ortiz","stage":"new_lead","dealValue":0}}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"Maya Ortiz","email":"maya@example.com","userId":"cust_123","phone":"+15551234567","company":"Ortiz Studio","dealValue":0,"currency":"USD","source":"other","tags":["api"]}}}}}},"/api/v1/users/{id}":{"get":{"operationId":"users.get","summary":"Fetch a contact by Targeted id or external userId.","description":"Includes recent transactions, activities, and bookings.","tags":["users"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"user":{"id":"clx…","userId":"cust_123","name":"Maya Ortiz"},"transactions":[],"activities":[],"bookings":[]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Targeted id or external userId.","schema":{"type":"string","example":"cust_123"}}]},"patch":{"operationId":"users.update","summary":"Update a contact by Targeted id or external userId.","tags":["users"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"user":{"id":"clx…","userId":"cust_123","stage":"contacted"}}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Targeted id or external userId.","schema":{"type":"string","example":"cust_123"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"company":"Ortiz Studio","stage":"contacted","tags":["api","vip"]}}}}}},"/api/v1/users/{id}/notes":{"post":{"operationId":"users.notes","summary":"Add a note to a contact timeline.","tags":["users"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"user":{"id":"clx…","name":"Maya Ortiz"}}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Targeted id or external userId.","schema":{"type":"string","example":"cust_123"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"body":"Called about the proposal."}}}}}},"/api/v1/users/{id}/payment-links":{"post":{"operationId":"users.paymentLinks","summary":"Create a checkout link for the deal balance.","description":"method is card, google_pay, or gcash. Uses Stripe, PayMongo, or the simulator when keys are missing.","tags":["users"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"ok":true,"url":"https://…","gateway":"simulator","transactionId":"clx…","emailed":false}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Targeted id or external userId.","schema":{"type":"string","example":"cust_123"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"method":"card"}}}}}},"/api/v1/deals":{"get":{"operationId":"deals.list","summary":"List pipeline deals.","description":"Optional query params: stage, paymentStatus.","tags":["deals"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"deals":[{"id":"clx…","name":"Maya Ortiz","stage":"proposal_sent","dealValue":2400,"paymentStatus":"unpaid"}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"stage","in":"query","required":false,"description":"Pipeline stage key.","schema":{"type":"string","example":"proposal_sent"}},{"name":"paymentStatus","in":"query","required":false,"description":"unpaid, pending, paid, partially_paid, refunded.","schema":{"type":"string","example":"unpaid"}}]},"post":{"operationId":"deals.create","summary":"Create a pipeline deal.","description":"dealValue is required and uses major units.","tags":["deals"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"deal":{"id":"clx…","name":"Maya Ortiz","dealValue":2400,"stage":"proposal_sent"}}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"Maya Ortiz","email":"maya@example.com","dealValue":2400,"currency":"USD","stage":"proposal_sent"}}}}}},"/api/v1/deals/{id}":{"get":{"operationId":"deals.get","summary":"Fetch a deal and its transactions.","tags":["deals"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"deal":{"id":"clx…","dealValue":2400,"stage":"proposal_sent"},"transactions":[]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Deal id.","schema":{"type":"string","example":"clx…"}}]},"patch":{"operationId":"deals.update","summary":"Update deal value, stage, or related fields.","tags":["deals"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"deal":{"id":"clx…","dealValue":2800,"stage":"won"}}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Deal id.","schema":{"type":"string","example":"clx…"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"dealValue":2800,"stage":"won"}}}}}},"/api/v1/bookings":{"get":{"operationId":"bookings.list","summary":"List upcoming bookings, or bookings in a date range.","description":"Without from/to, returns upcoming bookings. With from and to (ISO dates), returns that window (about one month max).","tags":["bookings"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"bookings":[{"id":"clx…","leadId":"clx…","name":"Session","startsAt":"2026-11-10T10:00:00.000Z","status":"booked"}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"from","in":"query","required":false,"description":"Range start ISO date.","schema":{"type":"string","example":"2026-11-01T00:00:00.000Z"}},{"name":"to","in":"query","required":false,"description":"Range end ISO date.","schema":{"type":"string","example":"2026-12-01T00:00:00.000Z"}}]},"post":{"operationId":"bookings.create","summary":"Create a calendar booking for a contact.","description":"Identify the contact with leadId, email, or userId. This is separate from custom tracking events.","tags":["bookings"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"booking":{"id":"clx…","leadId":"clx…","startsAt":"2026-11-20T09:00:00.000Z","status":"inquiry"}}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"email":"maya@example.com","name":"Portrait session","startsAt":"2026-11-20T09:00:00.000Z","venue":"Studio A","packageName":"Half day","status":"inquiry"}}}}}},"/api/v1/bookings/{id}":{"get":{"operationId":"bookings.get","summary":"Fetch one booking.","tags":["bookings"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"booking":{"id":"clx…","leadId":"clx…","name":"Portrait session","status":"booked"}}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Booking id.","schema":{"type":"string","example":"clx…"}}]},"patch":{"operationId":"bookings.update","summary":"Reschedule or update booking fields.","tags":["bookings"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"booking":{"id":"clx…","startsAt":"2026-11-21T11:00:00.000Z","status":"booked"}}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Booking id.","schema":{"type":"string","example":"clx…"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"startsAt":"2026-11-21T11:00:00.000Z","status":"booked"}}}}}},"/api/v1/events":{"post":{"operationId":"events.track","summary":"Record a custom activity event for a contact.","description":"Not a calendar booking. Custom event names can start workflows and appear in User Lookup.","tags":["events"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"leadId":"clx…","eventId":"clx…"}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"email":"person@example.com","event":"signed_up","data":{"plan":"starter"}}}}}}},"/api/v1/catalogs":{"get":{"operationId":"catalogs.list","summary":"List product catalogs and their fields.","tags":["catalogs"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"catalogs":[{"id":"clx…","name":"Portrait packages","itemCount":3,"fields":[]}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}}},"post":{"operationId":"catalogs.create","summary":"Create a product or package catalog.","tags":["catalogs"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"catalog":{"id":"clx…","name":"Portrait packages","itemCount":0,"fields":[]}}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"Portrait packages","description":"Studio packages","fields":[{"label":"Name","type":"text"},{"label":"Price","type":"number"}]}}}}}},"/api/v1/catalogs/{id}/items":{"get":{"operationId":"catalogs.items.list","summary":"List items in a catalog.","tags":["catalogs"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"items":[{"id":"clx…","itemKey":"half-day","data":{"name":"Half day","price":"900"}}],"total":1,"page":1}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Catalog id.","schema":{"type":"string","example":"clx…"}},{"name":"q","in":"query","required":false,"description":"Search item key or data.","schema":{"type":"string","example":"half"}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"string","example":"1"}}]},"post":{"operationId":"catalogs.items.create","summary":"Add an item to a catalog.","tags":["catalogs"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"ok":true,"itemKey":"half-day"}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Catalog id.","schema":{"type":"string","example":"clx…"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"itemKey":"half-day","data":{"name":"Half day","price":"900"}}}}}}},"/api/v1/catalogs/items/{id}":{"patch":{"operationId":"catalogs.items.update","summary":"Update a catalog item’s key and field data.","tags":["catalogs"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"ok":true,"itemKey":"half-day"}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Catalog item id.","schema":{"type":"string","example":"clx…"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"itemKey":"half-day","data":{"name":"Half day","price":"950"}}}}}},"delete":{"operationId":"catalogs.items.delete","summary":"Delete a catalog item by item id.","tags":["catalogs"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"ok":true}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Catalog item id.","schema":{"type":"string","example":"clx…"}}]}},"/api/v1/catalogs/search":{"get":{"operationId":"catalogs.search","summary":"Search items across catalogs.","tags":["catalogs"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"total":1,"items":[{"id":"clx…","label":"Portrait packages · Half day","packageName":"Half day"}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"q","in":"query","required":false,"description":"Search query.","schema":{"type":"string","example":"portrait"}},{"name":"limit","in":"query","required":false,"description":"Max results (1–20).","schema":{"type":"string","example":"10"}}]}},"/api/v1/campaigns":{"get":{"operationId":"campaigns.list","summary":"List campaigns (ids for trigger).","tags":["campaigns"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"campaigns":[{"id":"clx…","name":"Welcome","medium":"email","subject":"Welcome"}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}}}},"/api/v1/campaigns/{id}/trigger":{"post":{"operationId":"campaigns.trigger","summary":"Send an existing campaign to a contact.","tags":["campaigns"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"campaignId":"clx…","leadId":"clx…","medium":"email","detail":"Sent email “Welcome”","sent":true}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id.","schema":{"type":"string","example":"clx…"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"email":"person@example.com"}}}}}},"/api/v1/workflows":{"get":{"operationId":"workflows.list","summary":"List workflows and their start source.","tags":["workflows"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"workflows":[{"id":"clx…","name":"On signup","status":"active","startSource":"api"}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}}}},"/api/v1/workflows/{id}/trigger":{"post":{"operationId":"workflows.trigger","summary":"Start an API-triggered workflow for a contact.","description":"Workflow must be live with Start = API call.","tags":["workflows"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"leadId":"clx…","runId":"clx…","started":true}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Workflow id.","schema":{"type":"string","example":"clx…"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"email":"person@example.com","data":{"source":"checkout"}}}}}}},"/api/v1/journeys":{"get":{"operationId":"journeys.list","summary":"List journeys (alias of workflows).","tags":["journeys"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"journeys":[{"id":"clx…","name":"On signup","status":"active","startSource":"api"}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}}}},"/api/v1/journeys/{id}/trigger":{"post":{"operationId":"journeys.trigger","summary":"Start an API-triggered journey (same as workflow).","tags":["journeys"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"leadId":"clx…","runId":"clx…","started":true}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Journey / workflow id.","schema":{"type":"string","example":"clx…"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"email":"person@example.com"}}}}}},"/api/v1/segments":{"get":{"operationId":"segments.list","summary":"List audiences / segments.","tags":["segments"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"segments":[{"id":"clx…","name":"Unpaid proposals","leadCount":12}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}}}},"/api/v1/segments/preview":{"post":{"operationId":"segments.preview","summary":"Count and sample contacts matching filter rules.","tags":["segments"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"count":12,"leads":[{"id":"clx…","name":"Maya Ortiz","paymentStatus":"unpaid"}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"filterRules":{"combinator":"and","rules":[{"field":"paymentStatus","op":"eq","value":"unpaid"}]}}}}}}},"/api/v1/stages":{"get":{"operationId":"stages.list","summary":"List pipeline stage keys for user/deal writes.","tags":["stages"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"stages":[{"key":"new_lead","label":"New Lead","kind":"open","position":0}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}}}},"/api/v1/sms":{"post":{"operationId":"sms.send","summary":"Send SMS to a contact, segment, or booking window.","description":"Provide leadId or userId, segmentId, and/or eventStartsWithinDays.","tags":["sms"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"messages":[{"leadId":"clx…","to":"+15551234567","status":"simulated"}]}}}},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or revoked API key"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"body":"See you tomorrow!","userId":"cust_123"}}}}}}}}