List a client's contacts
List a client's contacts. Requires Manager, Admin or Owner. Member tokens receive 403 forbidden_scope — Members have no client access in Hoursmith. Read scope. Sorted by email, then id. Archived or unknown clients return 404. Also returns defaultInvoiceRecipient (billingEmail > billing-default contact > client email). Unknown or repeated query parameters return 422.
Authorization
BearerAuth Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.
In: header
Path Parameters
Client UUID.
Query Parameters
Opaque cursor from pagination.nextCursor; bound to this client.
Page size; default 100.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/clients/497f6eca-6276-4993-bfeb-53cbbbba6f08/contacts"{ "data": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "clientId": "5e505642-9024-474d-9434-e5a44f505cc5", "email": "user@example.com", "name": "string", "title": "string", "phone": "string", "isPrimary": true, "isBillingDefault": true, "portalEnabled": true, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" } ], "defaultInvoiceRecipient": { "email": "user@example.com", "source": "client_billing_email", "contactId": "b5ec5d98-4bee-4da1-ad24-dde86346cb1d" }, "pagination": { "limit": 1, "nextCursor": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}Delete a client (hard delete)
Requires Manager, Admin, or Owner. Member tokens receive 403 forbidden_scope.
Add a contact to a client
Requires Manager, Admin or Owner. Member tokens receive 403 forbidden_scope — Members have no client access in Hoursmith. Write scope. Sends no email. Confirmation rule (stateless, from the request alone): portalEnabled true requires confirmPortalAccess: true (the email may sign in to the client portal and see this client's invoices); isBillingDefault true requires confirmBillingDefault: true (invoice emails and automatic reminders default to this contact unless the client has its own billingEmail); on PATCH, supplying email requires confirmEmailChange: true. A missing acknowledgement is a 422 whose `fields` name the flag and why; nothing is changed. Turning a flag or portal access off never needs confirmation.