> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard the authenticated client to a project

> Idempotently registers the signed-in end user as a CLIENT of the project: ensures a ProjectUsers membership, creates Stripe's own Customer object on the project's connected account (when Stripe is configured, stored as stripeCustomerId), and writes the ClientProfile. Requires both an API key (`x-api-key`) and a client user JWT (`Authorization: Bearer`). Returns 201 on first onboarding, 200 if the client was already onboarded.

The body is optional; a call with no body (or `{}`) onboards without touching the name or phone. Send `firstName`, `lastName` and/or `phone` to record what your checkout collected: each provided field ALWAYS overwrites the value already stored, on every path (first onboarding, claiming an existing profile by email, or already onboarded), and is also copied to the client's Stripe customer. A blank or `null` field counts as not provided and never clears a stored value; use PATCH /clients/me to clear the phone.

Without names, the client is recorded under the names from their sign-in. A Google sign-in supplies real names, but an email/password sign-up has only the email address, so the client would appear under the part of it before the `@`. Names are trimmed and must be at most 80 characters. They are the client's record in this project only; they do not rename the person's MarketBox account. The phone is validated and stored in E.164 form (`+14165550134`). Send it as E.164, or as a national North American (NANP) number such as `(416) 555-0134`; numbers outside North America must start with `+` and the country code, or they are rejected. An invalid number is a 400 and nothing is written.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/clients/me
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/clients/me:
    post:
      tags:
        - Clients
      summary: Onboard the authenticated client to a project
      description: >-
        Idempotently registers the signed-in end user as a CLIENT of the
        project: ensures a ProjectUsers membership, creates Stripe's own
        Customer object on the project's connected account (when Stripe is
        configured, stored as stripeCustomerId), and writes the ClientProfile.
        Requires both an API key (`x-api-key`) and a client user JWT
        (`Authorization: Bearer`). Returns 201 on first onboarding, 200 if the
        client was already onboarded.


        The body is optional; a call with no body (or `{}`) onboards without
        touching the name or phone. Send `firstName`, `lastName` and/or `phone`
        to record what your checkout collected: each provided field ALWAYS
        overwrites the value already stored, on every path (first onboarding,
        claiming an existing profile by email, or already onboarded), and is
        also copied to the client's Stripe customer. A blank or `null` field
        counts as not provided and never clears a stored value; use PATCH
        /clients/me to clear the phone.


        Without names, the client is recorded under the names from their
        sign-in. A Google sign-in supplies real names, but an email/password
        sign-up has only the email address, so the client would appear under the
        part of it before the `@`. Names are trimmed and must be at most 80
        characters. They are the client's record in this project only; they do
        not rename the person's MarketBox account. The phone is validated and
        stored in E.164 form (`+14165550134`). Send it as E.164, or as a
        national North American (NANP) number such as `(416) 555-0134`; numbers
        outside North America must start with `+` and the country code, or they
        are rejected. An invalid number is a 400 and nothing is written.
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              The project (tenant) that owns the resource. Every resource in
              this API is scoped to a project, and your API key is restricted to
              the projects it was issued for — a project outside that scope
              returns 403.
            example: prj_01kv60qgnef2kt3pvqgwmkbzfr
          required: true
          description: >-
            The project (tenant) that owns the resource. Every resource in this
            API is scoped to a project, and your API key is restricted to the
            projects it was issued for — a project outside that scope returns
            403.
          name: projectId
          in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  nullable: true
                  description: >-
                    The client's first name as your checkout collected it, at
                    most 80 characters after trimming. Overwrites the stored
                    first name; blank or null means not provided.
                  example: Emma
                lastName:
                  type: string
                  nullable: true
                  description: >-
                    The client's last name as your checkout collected it, at
                    most 80 characters after trimming. Overwrites the stored
                    last name; blank or null means not provided.
                  example: Bishop
                phone:
                  type: string
                  nullable: true
                  description: >-
                    Phone number. Accepts E.164 or a national NANP number;
                    stored as E.164 (e.g. +14165550134).
                  example: '+14165550134'
      responses:
        '200':
          description: Client already onboarded
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ClientProfile'
                required:
                  - data
        '201':
          description: Client onboarded
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ClientProfile'
                required:
                  - data
        '400':
          description: Invalid name or phone number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Missing/invalid user token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: >-
            No access to project or unregistered user, or the membership here
            was deactivated (MEMBERSHIP_INACTIVE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Email already belongs to a different linked client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
        - ApiKeyAuth: []
          EndUserBearer: []
components:
  schemas:
    ClientProfile:
      type: object
      properties:
        entityType:
          type: string
          enum:
            - CLIENT_PROFILE
        clientId:
          type: string
        projectId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        firstNameNormalized:
          type: string
        lastNameNormalized:
          type: string
        fullNameNormalized:
          type: string
        email:
          type: string
        emailNormalized:
          type: string
        phone:
          type: string
        defaultAddressId:
          type: string
        externalId:
          type: string
        externalData:
          type: object
          additionalProperties:
            nullable: true
        userId:
          type: string
        invitationStatus:
          type: string
          enum:
            - NONE
            - INVITED
            - LINKED
        stripeCustomerId:
          type: string
          nullable: true
        stripeAccountId:
          type: string
          nullable: true
        notes:
          type: string
        lifetimeSpend:
          type: number
        orderCount:
          type: number
        lastPurchaseAt:
          type: string
        lastPaymentMethodId:
          type: string
        lastPayment:
          type: object
          properties:
            type:
              type: string
              enum:
                - CARD
            brand:
              type: string
            last4:
              type: string
              minLength: 4
              maxLength: 4
            expMonth:
              type: integer
              nullable: true
              minimum: 1
              maximum: 12
            expYear:
              type: integer
              nullable: true
            paidAt:
              type: string
          required:
            - type
            - brand
            - last4
            - paidAt
        defaultLocale:
          type: string
        active:
          type: boolean
        deleted:
          type: boolean
        createdAt:
          type: string
        updatedAt:
          type: string
        createdBy:
          type: string
        updatedBy:
          type: string
        addresses:
          type: array
          items:
            type: object
            properties:
              addressOneLine:
                type: string
                minLength: 1
                description: The whole address on one line, as a person would write it.
                example: 10 Main St, Toronto, ON M5V 1A1, Canada
              streetNumber:
                type: string
                minLength: 1
                description: The street number.
                example: '10'
              streetName:
                type: string
                minLength: 1
                description: The street name.
                example: Main St
              city:
                type: string
                minLength: 1
                description: The city or town.
                example: Toronto
              state:
                type: string
                minLength: 1
                description: >-
                  The state, province or region; an ISO 3166-2 code when one
                  matches.
                example: 'ON'
              country:
                type: string
                minLength: 1
                description: The country; ISO 3166-1 alpha-2, alpha-3 or the English name.
                example: CA
              zipCode:
                type: string
                minLength: 1
                description: The postal or ZIP code, in any national format.
                example: M5V 1A1
              unitNumber:
                type: string
                nullable: true
                description: The unit, suite or apartment, if any.
                example: 4B
              id:
                type: string
                minLength: 1
              source:
                type: string
                enum:
                  - BOOKING
                  - MANUAL
              latitude:
                type: number
                nullable: true
              longitude:
                type: number
                nullable: true
            required:
              - addressOneLine
              - streetNumber
              - streetName
              - city
              - state
              - country
              - zipCode
              - id
      required:
        - entityType
        - clientId
        - projectId
        - firstName
        - lastName
        - fullName
        - firstNameNormalized
        - lastNameNormalized
        - fullNameNormalized
        - email
        - emailNormalized
        - invitationStatus
        - stripeCustomerId
        - stripeAccountId
        - active
        - deleted
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
        - addresses
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.
    EndUserBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        The signed-in person's Cognito access token, issued to this
        application's app client. Sent with the API key on the /clients/me and
        /suppliers/me routes.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.