> ## Documentation Index > Fetch the complete documentation index at: https://docs.gaintrace.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or upsert a person > Adds a Person to a Company. - Name the Company with `accountId` or `accountExternalId`. - A Person who already exists at a **different** Company gets a new record at this one. Matching is by `externalId`, then `email`. That does not count against your People limit. - A Person who already exists at **this** Company fails with `409`, unless you send `upsert: true`. Then the record is updated and returned with `200`, and `traits` are merged. - A new Person counts against your People limit (`402` when it is reached). - With `accountExternalId`, an unknown Company is created for you and counts against your Company limit. It fires the `company.created` webhook with `source` set to `api`. It does not start Company-created Flows. - A new Person fires `contact.created`, and an upsert that updates a Person fires `contact.updated`, both with `source` set to `api`. This is the same operation as `POST /contacts`. **Scope:** `write:contacts` ## OpenAPI ````yaml /openapi.json post /people openapi: 3.1.0 info: title: GainTrace API version: 1.0.0 description: >- The GainTrace REST API (v1). Read your customer data and push product-usage events, metric events, and signals into GainTrace. All endpoints are authenticated with a Bearer API key and scoped to a single workspace. Each API key can send 60 requests a minute. A `429` response includes a `Retry-After` header with the seconds to wait. servers: - url: https://app.gaintrace.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Companies description: Read and manage canonical company records. - name: Signals description: Read, create, and manage buyer / risk signals. - name: Ingest description: Push product-usage and metric events into GainTrace. - name: Contacts description: >- The original path for People. It shares its handlers with /people, and also offers delete-by-key. - name: Webhooks description: Subscribe to workspace events with signed, retried delivery. - name: People description: Read and manage People. One Person can belong to many Companies. - name: NPS responses description: Import NPS scores from another survey tool and read your NPS history. - name: Surveys description: >- Create and launch surveys, request invitations, record responses and mint in-app sessions. - name: Survey responses description: Read the responses collected by your surveys. - name: Survey segments description: Save groups of Companies and People that surveys can target. - name: Survey imports description: Pull responses from the survey tools your workspace has connected. paths: /people: post: tags: - People summary: Create or upsert a person description: >- Adds a Person to a Company. - Name the Company with `accountId` or `accountExternalId`. - A Person who already exists at a **different** Company gets a new record at this one. Matching is by `externalId`, then `email`. That does not count against your People limit. - A Person who already exists at **this** Company fails with `409`, unless you send `upsert: true`. Then the record is updated and returned with `200`, and `traits` are merged. - A new Person counts against your People limit (`402` when it is reached). - With `accountExternalId`, an unknown Company is created for you and counts against your Company limit. It fires the `company.created` webhook with `source` set to `api`. It does not start Company-created Flows. - A new Person fires `contact.created`, and an upsert that updates a Person fires `contact.updated`, both with `source` set to `api`. This is the same operation as `POST /contacts`. **Scope:** `write:contacts` operationId: createPerson requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PersonCreate' example: accountExternalId: acme accountName: Acme Inc name: Ana Ruiz email: ana@acme.com externalId: user_8812 contactRole: decision_maker upsert: true traits: plan_tier: growth responses: '200': description: >- The Person already existed at this Company and `upsert` was true. The updated record. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Person' '201': description: Person created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Person' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' components: schemas: PersonCreate: type: object description: >- Create a Person at a Company, or with `upsert: true` create or update. Name the Company with `accountId` or `accountExternalId`. `name` is required unless `upsert` is true and an `email` is supplied, or the Person already exists at another Company. anyOf: - required: - accountId - required: - accountExternalId properties: accountId: type: string format: uuid description: The Company `id`. It must belong to your workspace. accountExternalId: type: string maxLength: 100 description: >- The Company `externalId`, used when you do not hold the Company `id`. If no Company has this `externalId`, GainTrace creates one, and that counts against your Company limit. The new Company fires the `company.created` webhook but does not start Company-created Flows. Ignored when `accountId` is a string. accountName: type: string description: >- The name for a Company created through `accountExternalId`. Defaults to the `externalId`. upsert: type: boolean default: false description: >- When true, a Person who already exists at this Company is updated and returned with `200`, instead of failing with `409`. `traits` are merged into the stored traits, not replaced. name: type: string maxLength: 255 minLength: 1 email: type: - string - 'null' format: email maxLength: 255 externalId: type: - string - 'null' maxLength: 255 phone: type: - string - 'null' maxLength: 50 role: type: - string - 'null' maxLength: 100 contactRole: $ref: '#/components/schemas/ContactRole' isChampion: type: boolean traits: type: - object - 'null' additionalProperties: true linkedinUrl: type: - string - 'null' maxLength: 2000 avatarUrl: type: - string - 'null' maxLength: 2000 Person: type: object description: >- One Person at one Company. A Person who belongs to several Companies is returned as one record per Company, each with its own `id` and `accountId`. properties: id: type: string format: uuid description: The id of this Person at this Company. accountId: type: string format: uuid description: The `id` of the Company this record belongs to. See Companies. name: type: string email: type: - string - 'null' format: email externalId: type: - string - 'null' description: >- Your own stable id for the Person, such as a Segment `userId`. Product events use it to find the Person. phone: type: - string - 'null' role: type: - string - 'null' description: Free-text job title. contactRole: anyOf: - $ref: '#/components/schemas/ContactRole' - type: 'null' description: The Person's role in the buying relationship. isChampion: type: - boolean - 'null' traits: type: object additionalProperties: true description: Free-form attributes. An empty object when none are set. linkedinUrl: type: - string - 'null' avatarUrl: type: - string - 'null' lastSeenAt: type: - string - 'null' format: date-time description: Read-only. engagementScore: type: - number - 'null' description: Read-only. createdAt: type: string format: date-time updatedAt: type: string format: date-time archivedAt: type: - string - 'null' format: date-time description: >- `null` while this record is live. Set when the Person left this Company or its source removed them. Archived records are left out of `GET /people` unless you send `includeArchived=true`. ContactRole: type: string enum: - decision_maker - champion - end_user - billing - influencer - executive_sponsor - technical - other Error: type: object required: - error description: The standard error envelope. Every 4xx/5xx response uses this shape. properties: error: type: object required: - code - message properties: code: type: string enum: - bad_request - unauthorized - payment_required - forbidden - not_found - conflict - unprocessable_entity - rate_limit_exceeded - internal_server_error - service_unavailable - gateway_timeout description: >- Stable, machine-readable error code. Each code maps to exactly one HTTP status. message: type: string description: >- Human-readable, safe description of what went wrong. Never contains internal or provider detail. doc_url: type: string format: uri example: https://docs.gaintrace.com/errors#not_found description: Deep link to this code in the Errors reference. responses: BadRequest: description: The request could not be parsed (for example, malformed JSON). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: bad_request message: Invalid JSON body doc_url: https://docs.gaintrace.com/errors#bad_request Unauthorized: description: Missing, malformed, expired, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Missing Authorization header doc_url: https://docs.gaintrace.com/errors#unauthorized PaymentRequired: description: >- A plan limit was reached, or billing is locked. Upgrade or enable pay-as-you-go. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: payment_required message: Monthly event limit reached. Upgrade or enable overage billing. doc_url: https://docs.gaintrace.com/errors#payment_required Forbidden: description: >- The key is valid but lacks the required scope, the origin is not allowed, or API v1 is not enabled for the workspace. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: 'Insufficient scope: write:companies required' doc_url: https://docs.gaintrace.com/errors#forbidden NotFound: description: >- The resource, or a resource you referenced, was not found in this workspace. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: Company not found doc_url: https://docs.gaintrace.com/errors#not_found Conflict: description: >- The request conflicts with an existing resource (for example, a duplicate email). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: conflict message: A contact with this email already exists in the workspace doc_url: https://docs.gaintrace.com/errors#conflict UnprocessableEntity: description: The request was well-formed but a value failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unprocessable_entity message: 'Request validation failed. name: name is required' doc_url: https://docs.gaintrace.com/errors#unprocessable_entity RateLimited: description: >- The per-key rate limit was exceeded. Each API key can send 60 requests per minute, counted in calendar-minute windows. The `Retry-After` header gives the whole seconds (1 to 60) until the next window opens. Wait that long, then retry. headers: Retry-After: description: Whole seconds until the next one-minute window starts. schema: type: integer minimum: 1 maximum: 60 example: 23 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limit_exceeded message: >- Can't accept more than 60 requests a minute from one API key. Retry in 23 seconds. doc_url: https://docs.gaintrace.com/errors#rate_limit_exceeded InternalServerError: description: >- An unexpected error occurred on our side. The failure is logged; retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_server_error message: Something went wrong. Try again in a moment. doc_url: https://docs.gaintrace.com/errors#internal_server_error ServiceUnavailable: description: >- A backing service (for example, the database) was temporarily unavailable. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: service_unavailable message: We had trouble reaching the database. Try again in a moment. doc_url: https://docs.gaintrace.com/errors#service_unavailable GatewayTimeout: description: >- The request took too long upstream before completing. Retry, and reduce batch size for large payloads. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: gateway_timeout message: The request timed out. Try again in a moment. doc_url: https://docs.gaintrace.com/errors#gateway_timeout securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer API key. Secret server keys start with `gt_live_`; client-safe browser keys start with `gt_pub_` (write-only, origin-pinned). Create and scope keys in Settings → API Keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.