Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.notealy.com/llms.txt

Use this file to discover all available pages before exploring further.

All non-2xx responses follow the same shape: 
{
  "statusCode": 400,
  "message": "phone must be 10–15 digits, optional leading +",
  "error": "Bad Request"
}
message may be an array when multiple validation errors are returned at once: 
{
  "statusCode": 400,
  "message": [
    "name is required and must not be empty",
    "phone must be 10–15 digits, optional leading +"
  ],
  "error": "Bad Request"
}

​
Common status codes

StatusMeaningRecovery
400 Bad RequestValidation failedFix the payload and retry
401 UnauthorizedToken missing, invalid, revoked or expiredIssue a new token
403 ForbiddenToken is valid but lacks the scope this endpoint requiresRe-issue the token with the right scopes
404 Not FoundResource id does not exist in your organizationConfirm the id and the org the token belongs to
409 ConflictUniqueness conflict (e.g. duplicate domain) — rare; most write endpoints upsert insteadRead the resource first
429 Too Many RequestsRate limit hitWait until X-RateLimit-Reset, then retry
5xxNotealy server errorRetry with exponential backoff

​
Idempotency

Several write endpoints are idempotent by design:
  • POST /v1/people upserts on phone → email → externalId.
  • POST /v1/companies upserts on domain.
  • POST /v1/people/:id/tags only emits contact.tag_added for newly attached tags.
Safe-to-retry responses make it easy to build at-least-once delivery from your side without duplicates on ours.