> ## Documentation Index > Fetch the complete documentation index at: https://docs.heffl.com/llms.txt > Use this file to discover all available pages before exploring further. # Create contact > Creates a new contact record. The contact is assigned to the user associated with your API key. Related entity IDs use prefixed string IDs (for example `clt_`, `cs_`, `usr_`). Custom field values use `cf_*` keys — see the [Custom fields](/api-v2/custom-fields) guide. ## OpenAPI ````yaml /openapi.v2.json post /contacts openapi: 3.1.1 info: title: Heffl API v2 (Beta) version: 2.0.0 description: >- Heffl REST API v2 (beta) — resource-oriented endpoints with consistent response envelopes. Endpoints, schemas, and behavior may change until GA. See Agent workflows and ID prefixes guides for automation. contact: name: Heffl Support url: https://heffl.com/support email: support@heffl.com servers: - url: https://api.heffl.com/api/v2 description: Production API Server security: - ApiKeyAuth: [] paths: /contacts: post: tags: - Objects summary: Create contact description: >- Creates a new contact record. The contact is assigned to the user associated with your API key. Related entity IDs use prefixed string IDs (for example `clt_`, `cs_`, `usr_`). Custom field values use `cf_*` keys — see the [Custom fields](/api-v2/custom-fields) guide. operationId: objects.contacts.create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ContactInput' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Contact' '400': description: Validation error or bad request content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '403': description: Insufficient permission content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/V2ApiError' components: schemas: ContactInput: type: object properties: firstName: type: string description: Contact first name lastName: type: string description: Contact last name salutation: type: string description: Title (Mr., Mrs., Dr., etc.) email: anyOf: - type: string format: email - type: 'null' description: Email address phone: type: string description: Phone number with country code jobTitle: type: string description: Job title or position companyId: type: string description: ID of the parent company to link this contact to stageId: type: string description: Client stage ID leadStageId: type: string description: Lead stage ID ownerUserId: type: string description: Owner user ID vendorId: type: string description: Vendor ID sourceId: type: string description: CRM source ID billingAddress: $ref: '#/components/schemas/BillingAddressInput' required: - firstName additionalProperties: description: >- Custom field values using cf_* keys (for example cf_industry). Only documented fields and cf_* keys are accepted. Contact: type: object properties: id: type: string description: Contact person's ID (clt_ prefix) name: type: string description: Display name number: type: string description: Auto-generated contact number type: anyOf: - type: string enum: - contact - company - type: 'null' description: Record type (always contact for this endpoint) firstName: type: string description: First name lastName: anyOf: - type: string - type: 'null' description: Last name email: anyOf: - type: string - type: 'null' description: Email address phone: anyOf: - type: string - type: 'null' description: Phone number salutation: anyOf: - type: string - type: 'null' description: Salutation jobTitle: anyOf: - type: string - type: 'null' description: Job title description: anyOf: - type: string - type: 'null' description: Description taxNumber: anyOf: - type: string - type: 'null' description: Tax number website: anyOf: - type: string - type: 'null' description: Website URL companyId: anyOf: - type: string - type: 'null' description: Parent company ID companyName: anyOf: - type: string - type: 'null' description: Parent company name parentClientId: anyOf: - type: string - type: 'null' description: Parent client ID (same as companyId for contacts) stageId: anyOf: - type: string - type: 'null' description: Client stage ID stageName: anyOf: - type: string - type: 'null' description: Client stage label leadStageId: anyOf: - type: string - type: 'null' description: Lead stage ID ownerUserId: anyOf: - type: string - type: 'null' description: Owner user ID crmSourceId: anyOf: - type: string - type: 'null' description: CRM source ID sourceName: anyOf: - type: string - type: 'null' description: CRM source name currency: anyOf: - type: string - type: 'null' description: Currency code openingBalance: type: number description: Opening balance showJobAmountToWorker: type: boolean description: Whether job amounts are visible to field workers isClientPortalEnabled: type: boolean description: Whether the client portal is enabled internalNotes: anyOf: - type: string - type: 'null' description: Internal notes profileImage: anyOf: - type: string - type: 'null' description: Profile image URL instagram: anyOf: - type: string - type: 'null' description: Instagram handle or URL facebook: anyOf: - type: string - type: 'null' description: Facebook handle or URL linkedin: anyOf: - type: string - type: 'null' description: LinkedIn handle or URL twitter: anyOf: - type: string - type: 'null' description: Twitter handle or URL createdAt: type: string format: date-time description: When the contact was created updatedAt: type: string format: date-time description: When the contact was last updated required: - id - name - number - firstName - openingBalance - showJobAmountToWorker - isClientPortalEnabled additionalProperties: description: >- Custom field values as top-level cf_* keys (for example cf_industry). There is no customFields wrapper. V2ApiError: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: type: object BillingAddressInput: type: object properties: city: anyOf: - type: string - type: 'null' description: City address: anyOf: - type: string - type: 'null' description: Street address landmark: anyOf: - type: string - type: 'null' description: Nearby landmark state: anyOf: - type: string - type: 'null' description: State or province country: anyOf: - type: string - type: 'null' description: Country code, ISO3 code, or country name postalCode: anyOf: - type: string - type: 'null' description: Postal code or ZIP code securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key for authentication. Get yours at app.heffl.com/settings/developers ````