> ## Documentation Index > Fetch the complete documentation index at: https://docs.truv.com/llms.txt > Use this file to discover all available pages before exploring further. # New User > Create an order where Truv contacts the user via email or SMS to complete verification Hosted orders let Truv handle user outreach. Create an order with the user's contact information, and Truv sends an email or SMS with a link to complete verification. No app or widget integration required. At least one of `email` or `phone` is required. Truv needs a way to contact the user. Providing both maximizes success rates. | Creation method | Best for | | ------------------- | -------------------------------------------- | | **API** | Programmatic workflows, automated pipelines | | **Dashboard** | Manual order creation, one-off verifications | | **CSV bulk upload** | High-volume batch processing | ```mermaid theme={null} sequenceDiagram participant Server as Your Server participant API as Truv API participant User as User Server->>API: 1. Create Order (POST /v1/orders/) API-->>Server: order_id, share_url API->>User: 2. Email/SMS with verification link User->>API: 3. User clicks link, connects accounts API-->>Server: 4. Webhook (task-status-updated) Server->>API: 5. Retrieve data (GET /v1/orders/{id}/) API-->>Server: Order with employer data, reports ``` *** ## How it works 1. **Create an order** via API with the user's contact information 2. **Truv sends a notification** (email, SMS, or both) with a link to the hosted verification page 3. **User connects accounts** on Truv's hosted page (payroll, banks) 4. **Receive data** via webhook notifications 5. **Retrieve results** using the order ID *** ## Implement ### Step 1: Create an order \[Server-side] Create an [Order](/api-reference/orders/object) with the user's name and contact information. Truv sends the verification link automatically. ```bash theme={null} curl --request POST \ --url https://prod.truv.com/v1/orders/ \ --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \ --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \ --header 'Content-Type: application/json' \ --data '{ "products": ["income"], "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "4155554193", "ssn": "222233333" }' ``` ```bash theme={null} curl --request POST \ --url https://prod.truv.com/v1/orders/ \ --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \ --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \ --header 'Content-Type: application/json' \ --data '{ "products": ["assets"], "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "4155554193" }' ``` ```bash theme={null} curl --request POST \ --url https://prod.truv.com/v1/orders/ \ --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \ --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \ --header 'Content-Type: application/json' \ --data '{ "products": ["income", "assets"], "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "4155554193", "ssn": "222233333" }' ``` The response includes a `short_share_url`, the hosted verification link to send to the user. ```json theme={null} { "id": "39aa1486ccca4bc19cda071ffc1ba392", "products": ["income"], "first_name": "John", "last_name": "Doe", "user_id": "99dd17074ac94aa9ace2621d657c7610", "bridge_token": "e4100fccdae94691b4414c7306220c06", // ... additional fields "short_share_url": "https://truv.link/abc123", // ... status, timestamps, employers } ``` Specify only the products your use case requires. | Field | Type | Required | Description | | ------------------ | ------ | -------- | ------------------------------------------------------------ | | `products` | array | Yes | Products to request: `income`, `employment`, `assets` | | `first_name` | string | Yes | User's first name | | `last_name` | string | Yes | User's last name | | `email` | string | Yes\* | User's email for notifications | | `phone` | string | No | User's phone for SMS notifications | | `ssn` | string | No | SSN for identity matching (4 or 9 digits) | | `external_user_id` | string | No | Your internal user/application identifier | | `template_id` | string | No | [Customization template](/developers/customization) to apply | If you already know the user's employer, use [deeplinking](/developers/integration/hosted-orders/deeplinking) to skip the search screen. ### Step 2: Test in sandbox Test your implementation with sandbox credentials. | Username | Password | Description | | ---------------------- | -------------- | ---------------------------- | | `goodlogin` | `goodpassword` | Full-time current employment | | `hourly.part-time` | `goodpassword` | Hourly part-time worker | | `multiple.employments` | `goodpassword` | Multiple employers | See [Test Credentials](/developers/testing/test-credentials) for all scenarios. ### Step 3: Monitor webhooks \[Server-side] [Webhooks](/api-reference/webhooks) notify you when task and order statuses change. Use `user_id` to match events to a specific order. ```mermaid theme={null} sequenceDiagram participant User participant API as Truv API participant Server as Your Server User->>API: Connects account via hosted page API-->>Server: task-status-updated (login) API-->>Server: task-status-updated (parse) API-->>Server: task-status-updated (done) User->>API: Clicks "I'm done" API-->>Server: order-status-updated (completed) ``` Task-level webhook, fires as each connection progresses. ```json theme={null} { "webhook_id": "17a80437ce23411dbfd656694d19a8c6", "event_type": "task-status-updated", "event_created_at": "2024-07-11T21:43:08.073930Z", "product": "income", "link_id": "d8a8945ee2b049b193110cfba643f5df", "user_id": "adbe707dddee4334bffaeb5866272740", "data_source": "payroll", "task_id": "871fef2e79ea444ea2019c8845305d31", "tracking_info": null, "status": "done", "template_id": null, "updated_at": "2024-07-11T21:43:08.075540+00:00" } ``` Order-level webhook, fires when the user finishes the order. ```json theme={null} { "webhook_id": "0aac461e7b774a38a72fd9c7c0eef8ee", "event_type": "order-status-updated", "event_created_at": "2024-07-11T21:40:48.424610Z", "product": "income", "link_id": "d8a8945ee2b049b193110cfba643f5df", "user_id": "adbe707dddee4334bffaeb5866272740", "data_source": "payroll", "order_id": "ddd192646b3c48be96651a0ff25cef85", "order_number": "4138538", "employer_id": "d7166cffbfef4bd6a9e830cf5508e615", "status": "completed", "template_id": null, "updated_at": "2024-07-11T21:40:48.424655+00:00" } ``` See [Task lifecycle](/api-reference/tasks/lifecycle) for all status transitions. ### Step 4: Retrieve data \[Server-side] Fetch order details using the `order_id`. The response includes employer data, employment history, income statements, and report IDs. ```bash theme={null} curl --request GET \ --url https://prod.truv.com/v1/orders/39aa1486ccca4bc19cda071ffc1ba392/ \ --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \ --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \ --header 'Accept: application/json' ``` See [Order object](/api-reference/orders/object) for the full response schema. *** ## Order statuses | Status | Description | | ------------- | ------------------------------------------------ | | **Pending** | Order created, system processing | | **Sent** | Email or SMS sent to the user | | **Completed** | User connected their account | | **Error** | Notification delivery failed | | **Canceled** | Order manually canceled | | **Expired** | Order exceeded its expiration window | | **Skipped** | User opened the link but did not complete | | **No Data** | User connected but the provider returned no data | *** ## No-code alternative Create orders through the Dashboard UI without any API integration: single orders or bulk via CSV. See [Manual Orders](/developers/integration/manual-orders/new-user). *** ## Set expiration and reminders The default expiration window is **72 hours**, configurable from 1 day to 12 weeks. Expiration periods do not count weekends. Configure expiration and automatic reminders in the [Dashboard](/developers/dashboard) under **Customization**, or set `expired_at` when creating orders via API. *** ## Next steps Add additional employers to an existing order Refresh data from existing connections Pre-fill employer info to skip search Let users review and confirm retrieved data Send verification links via email/SMS. The applicant completes Bridge on their own device.