> ## Documentation Index > Fetch the complete documentation index at: https://developers.firstbase.com/llms.txt > Use this file to discover all available pages before exploring further. # Offboard person > Starts offboarding for the person. May create return workflows depending on request body options (for example address confirmation and items not to return). ## OpenAPI ````yaml /openapi.json post /api/v1/people/{personId}/offboard openapi: 3.1.0 info: title: Firstbase API Specification description: Integration endpoints for Firstbase version: 0.1.0 servers: - url: http://localhost:8081 description: Production security: - ApiKey: [] tags: - name: Catalog description: Browse SKUs, brands, and categories - name: Inventory description: Query and manage inventory items and assets - name: Inventory Levels description: Configure inventory levels by SKU and warehouse - name: Inventory Orders description: Create and manage inventory orders - name: ITAD description: IT asset disposition requests - name: New Joiners description: Track and remind new joiners - name: Offices description: Manage office locations - name: Orders description: Create and track equipment orders - name: Packages description: Manage equipment packages - name: People description: Provision and manage users - name: Regions description: Query regions - name: Replacements description: Create and manage equipment replacements - name: Returns description: Create and manage returns - name: Shipment description: Look up shipments and carriers - name: Shipment Notices description: Create and manage shipment notices - name: Warehouses description: Query warehouses paths: /api/v1/people/{personId}/offboard: post: tags: - People summary: Offboard person description: >- Starts offboarding for the person. May create return workflows depending on request body options (for example address confirmation and items not to return). operationId: offboard parameters: - name: personId in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/OffboardPersonRequest' example: itemsToReturn: [] itemsToNotReturn: [] address: addressLine1: 123 addressLine2: Suite 103 administrativeArea: NY countryCode: US locality: New York City postalCode: 10123 phoneNumber: 555-867-5309 required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/Person' '400': description: >- Validation or business rule error. Returns source "ASSET_TRACKING_ONLY_GEO" when the destination country or region is configured as asset-tracking-only for shipment return paths (SHIP_TO_FIRSTBASE, SHIP_TO_OFFICE). content: '*/*': schema: $ref: '#/components/schemas/PublicApiHttpErrors' '403': description: Contract tier not available or feature flag disabled content: '*/*': schema: $ref: '#/components/schemas/PublicApiHttpErrors' '404': description: Person not found content: '*/*': schema: $ref: '#/components/schemas/PublicApiHttpErrors' '409': description: Conflict content: '*/*': schema: $ref: '#/components/schemas/PublicApiHttpErrors' x-codeSamples: - lang: curl label: cURL source: >- curl -sS -X POST 'http://localhost:8081/api/v1/people/{personId}/offboard' \ -H 'Authorization: ApiKey YOUR_API_KEY' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "itemsToReturn": [], "itemsToNotReturn": [], "address": { "addressLine1": 123, "addressLine2": "Suite 103", "administrativeArea": "NY", "countryCode": "US", "locality": "New York City", "postalCode": 10123, "phoneNumber": "555-867-5309" } }' components: schemas: OffboardPersonRequest: type: object properties: personLastDate: type: string format: date description: Employee's last working date. returnType: type: string description: How the equipment will be returned. enum: - SHIP_TO_FIRSTBASE - SHIP_TO_OFFICE - DROPPED_TO_OFFICE officeId: type: string format: uuid description: >- Office ID. Required for SHIP_TO_OFFICE and DROPPED_TO_OFFICE return types. itemsToReturn: type: array description: >- Equipment to be returned or dropped off at the office. Behavior depends on returnType: ship paths create a return order; DROPPED_TO_OFFICE assigns inventory to officeId. Every eligible inventory item must appear in exactly one of itemsToReturn or itemsToNotReturn. Must-return (Firstbase-supplied HaaS) items must be listed here. items: $ref: '#/components/schemas/OffboardItemToReturn' itemsToNotReturn: type: array description: >- Equipment NOT being returned (with deploy reasons). Every eligible inventory item must appear in exactly one of itemsToReturn or itemsToNotReturn. items: $ref: '#/components/schemas/OffboardItemToNotReturn' address: $ref: '#/components/schemas/OffboardAddressInfo' description: >- Confirmed shipping address. Only allowed when addressValidationNeeded=false with a ship return type (SHIP_TO_FIRSTBASE/SHIP_TO_OFFICE) that has itemsToReturn. When supplied it overwrites the person's stored home address and is used for the return order. phoneNumber is optional; when omitted the person's existing phone number is preserved. addressValidationNeeded: type: boolean default: true description: >- When true (default), employee confirms shipping address before the return kit is sent. When false, the return order is auto-confirmed using the admin-supplied address; if there are no items to return, the person transitions directly to INACTIVE. required: - personLastDate - returnType Person: type: object description: A person (employee) record in Firstbase properties: id: type: string format: uuid description: Unique identifier for this person example: e2bd9633-46b4-4286-85bd-3403a3f17e0f role: type: string description: >- Role of this person within the organization (BASIC = standard employee, ADMIN = org admin) enum: - BASIC - ADMIN example: BASIC firstName: type: string description: First name of the person example: Jenny lastName: type: string description: Last name of the person example: Smith identityEmail: type: string description: Identity email address, used for platform login and notifications example: jenny@example.com email: type: string description: Primary email address, used for platform login and notifications example: jenny@example.com secondaryEmail: type: string description: Secondary email address; null when not provided example: jenny@secondary.example.com phoneNumber: type: string description: Phone number from the person's home address; null when not provided example: 555-867-5309 startDate: type: string format: date description: Employment start date, used to trigger onboarding timelines example: '2023-11-22' homeAddress: $ref: '#/components/schemas/AddressInfo' description: Home address of the person, used for equipment deliveries package: $ref: '#/components/schemas/Package' description: >- Equipment package currently assigned to this person; null when no package is assigned status: type: string description: >- Current lifecycle status of the person in Firstbase (e.g. INVITED, ACTIVE, OFFBOARDING) enum: - INVITED - ACTIVE - INACTIVE - DELETED - OFFBOARDING - CANNOT_REACTIVATE cpfNumber: type: string description: Brazilian CPF tax number; null for non-Brazilian employees example: 87523654789 required: - firstName - id - lastName - role - status PublicApiHttpErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/PublicApiError' description: List of error details. required: - errors OffboardItemToReturn: type: object properties: inventoryId: type: string format: uuid description: Inventory ID being returned or dropped off at office. returnReasonComment: type: string description: >- Optional free-text comment about the return. Only used for ship return types (SHIP_TO_FIRSTBASE, SHIP_TO_OFFICE). Rejected when non-blank on DROPPED_TO_OFFICE. maxLength: 500 minLength: 0 itad: type: boolean description: >- Whether to elect ITAD (IT Asset Disposition) for this item. Only used for ship return types. Not allowed for subscription/HaaS items. Rejected when true on DROPPED_TO_OFFICE. holdRequested: type: boolean description: >- Whether to request a machine retention hold for this item. Only used for ship return types. Only available when this capability is enabled for your organization. When available and the organization's retention policy for the person's region is AD_HOC, set to true to request a hold. Omitted or null is treated as false. Sending this field when the capability is unavailable returns 403. Rejected when true on DROPPED_TO_OFFICE. required: - inventoryId OffboardItemToNotReturn: type: object properties: inventoryId: type: string format: uuid description: Inventory ID NOT being returned. deployReason: type: string description: Reason this item is not being returned. enum: - ASSIGNED_TO_ADMIN - AWAITING_INFORMATION - BOUGHT_OUT - CANCELLED_BY_FIRSTBASE - CANCELLED_BY_VENDOR - CHURNED_CUSTOMER - DATA_ERROR - DATA_HOLD - DECOMMISSIONED_BY_EMPLOYER - DECOMMISSIONED_BY_FIRSTBASE - END_OF_USEFUL_LIFE_DESTROYED - END_OF_USEFUL_LIFE_DONATED - PENDING_FULFILLMENT - GIFTED_BY_EMPLOYER - GIFTED_BY_FIRSTBASE - IN_TRANSIT - LOCKED_APPLE_ACTIVATION - LOCKED_FMD_REPORTED_LOST_STOLEN - LOCKED_MDM - LOCKED_PIN - LOST_BY_FIRSTBASE - LOST_IN_TRANSIT - LOST_BY_WORKER - MARKED_FOR_DESTRUCTION - NA - NEVER_RECEIVED_BY_WORKER - NEVER_RETURNED_BY_WORKER - OTHER - OUT_FOR_DESTRUCTION - OUT_FOR_REPAIR - PENDING_BUY_OUT - PENDING_HOLD_RELEASE - RECYCLING_REQUESTED - REQUIRES_CLEANING - REQUIRES_REPAIR - RETURN_IN_PROGRESS - SENT_TO_OFFICE - STOLEN - UNRESPONSIVE_WORKER - UNSUPPORTED_REGION - PERSONAL_DEVICE deployReasonDetail: type: string description: >- Free-text detail. Required when deployReason is OTHER. Maximum 35 characters. maxLength: 35 minLength: 0 required: - deployReason - inventoryId OffboardAddressInfo: type: object properties: addressLine1: type: string description: Street address line 1 example: 123 addressLine2: type: string description: Street address line 2 example: Suite 103 administrativeArea: type: string description: the state or county example: NY countryCode: type: string description: ISO 3166-1 alpha-2 country code example: US locality: type: string description: the city example: New York City postalCode: type: string description: the postal code or zip code example: 10123 phoneNumber: type: string description: >- Phone number for the return shipping address. When omitted, the person's existing phone number is preserved. example: 555-867-5309 required: - countryCode AddressInfo: type: object properties: addressLine1: type: string description: Street address line 1 example: 123 addressLine2: type: string description: Street address line 2 example: Suite 103 administrativeArea: type: string description: State, province, or county example: NY countryCode: type: string description: ISO 3166-1 alpha-2 country code example: US locality: type: string description: City or locality example: New York City postalCode: type: string description: Postal code or ZIP code example: 10123 required: - countryCode Package: type: object description: >- An equipment package (onboarding bundle) that can be assigned to a person properties: id: type: string format: uuid description: Unique identifier for this package example: 3a68a467-8733-4c8d-a942-16ed7ec33018 name: type: string description: Display name of the package example: The works automaticOrder: type: boolean description: >- When true, an equipment order is placed automatically when a person with this package is onboarded example: false approvalRequired: type: boolean description: >- When true, orders from this package require manager approval before being processed example: false requireJustification: type: boolean description: When true, order items in this package require a justification example: false active: type: boolean description: >- Whether this package is currently active. Inactive packages cannot be used for new assignments example: true skuIds: type: array description: >- List of SKU IDs included in this package; null when no SKUs are configured examples: - 3cf416c1-1b0f-4344-9cec-ba9c9fe615c9 items: type: string format: uuid assignedTo: $ref: '#/components/schemas/PackageAssignedToInformation' description: People and groups currently assigned to this package required: - active - approvalRequired - assignedTo - automaticOrder - id - name - requireJustification PublicApiError: type: object properties: detail: type: string description: Human-readable description of the error example: Invalid request source: type: string description: >- Entity or field path that caused the error (for example order, shipmentNotice, or person:email) example: request required: - detail - source PackageAssignedToInformation: type: object properties: people: type: array description: >- List of people assigned to this package. Each entry contains identifying information for a person linked to this package assignment. examples: - 3cf416c1-1b0f-4344-9cec-ba9c9fe615c9 items: type: string format: uuid securitySchemes: ApiKey: type: apiKey description: Prefix the value with "ApiKey" to indicate the custom authorization type name: Authorization in: header ````