> ## Documentation Index > Fetch the complete documentation index at: https://talktohumans.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Write draft > Create or replace a message, connection request, or sequence draft ## OpenAPI ````yaml /developers/openapi.yaml post /v1/drafts openapi: 3.0.3 info: title: TalkToHumans Public API version: 1.0.0 license: name: Proprietary description: > Read and organize the LinkedIn organization data your team already manages in TalkToHumans: accounts, contacts, tags, notes, sequence state, conversations, templates, and views. servers: - url: https://api.talktohumans.app description: TalkToHumans API security: - bearerAuth: [] tags: - name: Organization description: Organization details for the current API key. - name: LinkedIn description: LinkedIn accounts, contacts, companies, and conversations. - name: Activity description: Activity for organization reporting. - name: Enrich description: Profile enrichment for LinkedIn contacts and companies. - name: Views description: Saved TalkToHumans views. - name: Templates description: Message and sequence templates. paths: /v1/drafts: post: tags: - LinkedIn summary: Write draft description: Create or replace a message, connection request, or sequence draft operationId: createMessageDraft requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMessageDraftRequest' examples: contact: summary: Draft a new message to an imported contact value: account_id: '42' contact_id: '123' draft_message: Hi Jane, it was great learning about Acme. conversation: summary: Draft a reply to an existing conversation value: account_id: '42' conversation_id: chat_abc123 draft_message: Thanks for the thoughtful note. Would Tuesday work? sequence: summary: Draft a sequence for a contact value: account_id: '42' contact_id: '123' steps: - type: connection_request delay_minutes: 0 content: Hi {{first_name}}, I'd love to connect. - type: message delay_minutes: 4320 content: >- Thanks for connecting, {{first_name}}! How is everything at {{company_name}}? template: summary: Draft a message from a template value: account_id: '42' contact_id: '123' template_id: tpl_6f1d2c3a-8b4e-4f5a-9c7d-2e1b0a9f8c7d variables: event_name: SaaStr Annual responses: '200': description: Draft saved in TalkToHumans. The message was not sent. content: application/json: schema: $ref: '#/components/schemas/CreateMessageDraftEnvelope' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccountScopedForbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CreateMessageDraftRequest: type: object additionalProperties: false description: > Provide exactly one target: `conversation_id` or `contact_id`. Provide exactly one of `draft_message`, `steps`, or `template_id`. required: - account_id oneOf: - required: - conversation_id - required: - contact_id properties: account_id: type: string description: LinkedIn account ID returned by `GET /v1/accounts`. pattern: ^[1-9][0-9]*$ conversation_id: type: string minLength: 1 description: >- Existing conversation ID returned by `GET /v1/conversations`. Provide exactly one target. contact_id: type: string pattern: ^[1-9][0-9]*$ description: >- Contact ID returned by `GET /v1/contacts` or a contact import's results. Provide exactly one target. draft_message: type: string minLength: 1 description: >- Plain-text draft. Surrounding whitespace is trimmed and the existing draft for the selected compose context is replaced. Provide exactly one of `draft_message`, `steps`, or `template_id`. steps: type: array minItems: 1 description: >- Ordered sequence steps staged in the conversation for the user to launch in TalkToHumans. Provide exactly one of `draft_message`, `steps`, or `template_id`. items: $ref: '#/components/schemas/TemplateStep' template_id: type: string minLength: 1 description: >- Template ID returned by `GET /v1/templates`. Writes the draft from a message or sequence template. Provide exactly one of `draft_message`, `steps`, or `template_id`. variables: type: object description: > Values for the template's own `{{key}}` variables, keyed by variable key. Only with `template_id`. Variables can be left unfilled by omitting them or passing an empty value; they stay in the draft for the user to fill in TalkToHumans. Keys the template does not use return `400 bad_request` listing them. additionalProperties: type: string CreateMessageDraftEnvelope: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/CreateMessageDraftResponse' TemplateStep: type: object additionalProperties: false required: - type - delay_minutes properties: type: type: string enum: - message - connection_request delay_minutes: type: integer minimum: 0 description: >- Minutes to wait after the previous step, or after launch for the first step. content: type: string description: >- Plain-text message, required for message steps. For connection requests, the optional note, up to 200 characters. CreateMessageDraftResponse: type: object additionalProperties: false required: - draft properties: draft: $ref: '#/components/schemas/MessageDraft' Error: type: object additionalProperties: false required: - code - message properties: code: type: string description: Machine-readable error code. enum: - unauthorized - forbidden - not_found - bad_request - internal_error - conflict - rate_limit_exceeded - account_shared_access_required - billing_payment_failed - billing_subscription_incomplete - billing_subscription_expired - billing_grace_period - billing_feature_not_available - billing_insufficient_credits - billing_invalid - enrichment_failed - enrichment_in_progress - linkedin_profile_not_found message: type: string description: Human-readable error message. debug: type: string description: Development-only debug details. MessageDraft: type: object additionalProperties: false required: - account - remaining_variables - app_url - updated_at oneOf: - required: - conversation_id - required: - contact_id properties: conversation_id: type: string description: >- Existing TalkToHumans conversation ID when the draft targets a conversation. contact_id: type: string description: >- TalkToHumans contact ID when the draft targets that contact's compose context. account: $ref: '#/components/schemas/AccountSummary' template_id: type: string description: >- Template the draft was written from. Sending the draft from TalkToHumans counts toward the template's statistics. draft_message: type: string description: >- Normalized plain-text content saved in the composer. Omitted for sequence drafts. steps: type: array description: >- Sequence steps staged in the conversation, present for sequence drafts. Launch them in TalkToHumans. items: $ref: '#/components/schemas/TemplateStep' remaining_variables: type: array description: > `{{key}}` variables still in the draft. Contact and company variables such as `first_name` or `company_name` are filled when the message is sent; other variables must be filled in TalkToHumans before sending. items: type: string app_url: type: string format: uri description: >- Opens the existing conversation or the new-message composer with the contact selected. updated_at: type: string format: date-time AccountSummary: type: object additionalProperties: false required: - account_id - display_name - provider_account_id - owner_user_id properties: account_id: type: string description: TalkToHumans account ID. display_name: type: string provider_account_id: type: string description: LinkedIn provider account ID. owner_user_id: type: string description: TalkToHumans user ID that owns the account. responses: BadRequest: description: Invalid request. `message` explains what to fix. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: bad_request message: invalid type for field "account_id" Unauthorized: description: Missing, malformed, invalid, or retired local API key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingAuthorization: value: code: unauthorized message: Authorization header is required invalidAuthorizationFormat: value: code: unauthorized message: Authorization header must use Bearer scheme invalidAPIKey: value: code: unauthorized message: Invalid API key AccountScopedForbidden: description: >- API access is not enabled for the organization, the API key cannot resolve to an active organization user, or the credential cannot access the requested LinkedIn account. content: application/json: schema: $ref: '#/components/schemas/Error' examples: accountSharedAccessRequired: summary: Requested account is not accessible to this credential value: code: account_shared_access_required message: >- This account is not shared-access enabled for API or MCP. Ask an admin to enable shared access before using this account from this credential. forbidden: value: code: forbidden message: you don't have access to this organization featureUnavailable: value: code: billing_feature_not_available message: >- Feature 'TalkToHumansAPI' is not available in your current plan insufficientCredits: value: code: billing_insufficient_credits message: Insufficient credits apiKeyPrincipalInvalid: value: code: forbidden message: >- This API key is no longer linked to an active organization user. Ask an organization admin to regenerate it NotFound: description: Requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_found message: participant not found RateLimited: description: >- Rate limit exceeded. Public routes allow 50 requests per 10 seconds per IP and endpoint. headers: Retry-After: description: Seconds to wait before retrying the request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limit_exceeded message: Rate limit exceeded InternalServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_error message: An internal error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: 'Pass API key as `Authorization: Bearer `.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.