> For the complete documentation index, see [llms.txt](https://docs.tendar.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tendar.co/documentation/onboarding/user-management.md). # User Management Users are at the center of everything you build with Tendar. Before you can run a credit check, disburse a loan, or collect a repayment, the person on the other end needs to exist as a user inside the Onboarding Service. This guide walks you through the complete lifecycle of a user - from creation to verification to bulk operations - So you can integrate with Tendar seamlessly. ### Before you begin *** Make sure you have: * Your **secret key** from the [Tendar dashboard](https://app.tendar.co/services?service-level=api-keys-and-webhooks). * A server-side environment to make API calls (never expose your secret key in client-side code). * All requests must include the `Authorization` header: ```http Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx ``` Every user you create is automatically scoped to your company. You will never see another company's data, and they will never see yours. ### The user object *** When you create a user, Tendar stores a profile with the fields below. Understanding this object helps you decide what to collect from your customers and what Tendar computes automatically. | Field | Type | Description | | --------------------- | --------- | ------------------------------------------------------------------------------------------------- | | `id` | string | Internal Tendar ID. Useful for internal references. | | `user_id` | string | A unique identifier for the user. You can supply your own or let Tendar generate one (`usr-xxx`). | | `first_name` | string | User's first name. | | `last_name` | string | User's last name. | | `middle_name` | string | User's middle name (optional). | | `email` | string | Email address. Must be a valid email format. Unique per role within your company. | | `phone` | string | Phone number in **E.164** international format, e.g. `+2348012345678`. | | `date_of_birth` | string | Date of birth in `DD/MM/YYYY` format. Tendar auto-calculates the `age` field from this. | | `gender` | string | One of `male`, `female`, or `others`. | | `address` | string | Full address. | | `country` | string | Country name in lowercase, e.g. `nigeria`. Tendar auto-derives the `country_code` (e.g. `NG`). | | `state` | string | State of residence. | | `city` | string | City of residence. | | `country_code` | string | *Auto-generated.* Two-letter country code derived from `country`. | | `image` | string | URL to the user's profile image (optional). | | `employment_status` | string | One of `employed`, `self-employed`, `contract-worker`, `business-owner`, `student`, `unemployed`. | | `years_of_employment` | integer | Number of years the user has been employed (optional). | | `email_verified` | boolean | Whether the email has been verified through Tendar's verification flow. | | `phone_verified` | boolean | Whether the phone number has been verified. | | `active` | boolean | Whether the user is active. Defaults to `true`. | | `role` | string | Always `customer` for users created through the API. | | `age` | integer | *Auto-calculated* from `date_of_birth`. | | `metadata` | object | A flexible key-value store for any custom data you want to attach to the user. | | `created_at` | timestamp | When the user was created. | | `updated_at` | timestamp | When the user was last updated. | {% hint style="info" %} The `metadata` field is a great place to store your platform's own internal IDs, tags, or any custom attributes that don't map to a standard Tendar field. It accepts any valid JSON object. {% endhint %} ### Create a user *** Creating a user is the first step of every onboarding flow. Send the user's profile information to the API, and Tendar returns a full user object with a `user_id` that you'll reference across every other service. **Endpoint** ```http POST /api/v1/user/create ``` **Request body** ```json { "user_id": "", "first_name": "John", "last_name": "Doe", "middle_name": "", "email": "johndoe@example.com", "phone": "+2348012345678", "date_of_birth": "01/01/1990", "gender": "male", "country": "nigeria", "state": "lagos", "city": "ikeja", "address": "No 1, John Doe Street, Ikeja, Lagos", "image": "", "employment_status": "employed", "years_of_employment": 3, "active": true, "metadata": {} } ``` **A few things to know:** * **`user_id`** - If you leave this empty, Tendar generates a unique ID like `usr-lyfriztafj`. If you already have your own user identifier (from your database, for example), pass it here and Tendar will use it instead. This makes it easy to correlate Tendar users with your existing records. If another user already has that `user_id`, the API returns a `400` with `"user already exists"`. * **Duplicate handling -** If a user with the same `email` already exists under your company, Tendar returns the existing user instead of creating a duplicate. If you pass a custom `user_id` and a user with that email already exists, Tendar updates the existing user's `user_id` to the one you provided and returns the user. This makes the endpoint idempotent and safe to retry. * **Auto-computed fields** - You don't need to calculate `age` or `country_code`. Tendar derives `age` from the `date_of_birth` and `country_code` from the `country` name automatically. * **Role** - Users created through the API are always customers. The `role` field may be omitted; if you send it, it must be `customer`. * **Billing** - Creating a user is a billable action (`customer.create`). Tendar charges your wallet based on your subscription's pricing plan, so make sure your wallet has sufficient balance. When the request returns an existing user (see duplicate handling above), nothing is charged. **Response** `200 OK` ```json { "data": { "id": "67ad212f3d5b0234cbb53527", "user_id": "usr-lyfriztafj", "first_name": "John", "last_name": "Doe", "middle_name": "", "email": "johndoe@example.com", "phone": "+2348012345678", "date_of_birth": "01/01/1990", "gender": "male", "country": "nigeria", "state": "lagos", "city": "ikeja", "country_code": "NG", "address": "No 1, John Doe Street, Ikeja, Lagos", "image": "", "employment_status": "employed", "years_of_employment": 0, "email_verified": false, "phone_verified": false, "active": true, "role": "customer", "age": 35, "metadata": {}, "created_at": "2025-02-12T22:31:11.619Z", "updated_at": "2025-02-12T22:31:11.619Z" }, "error": false, "message": "User created successfully" } ``` Notice that `email_verified` and `phone_verified` are both `false`. The user exists, but their contact details haven't been confirmed yet. The next section shows you how to change that. ### Verify a user's email *** Email verification is a two-step process: you ask Tendar to send a verification code to the user's email, and then you submit the code the user provides back to Tendar. {% stepper %} {% step %} #### Send the verification code ```http GET /api/v1/user/email-verification/send/:user_id ``` Replace `:user_id` with the user's `user_id` (e.g. `usr-lyfriztafj`). Tendar sends a 6-digit code to the email address on file. The code expires after **10 minutes**. **Response** ```json { "error": false, "message": "Email verification token sent successfully" } ``` > If the user's email is already verified, the API returns a `400` error with the message `"email already verified"`. If the user has no email on file, it returns a `400` with `"email address not found for this user"`. > {% endstep %} {% step %} #### Submit the code ```http POST /api/v1/user/email-verification/verify/:user_id ``` **Request body** ```json { "token": "442974" } ``` **Response** ```json { "error": false, "message": "Email verified successfully" } ``` Once verified, the user's `email_verified` field flips to `true`. This is a one-time action — subsequent calls to the send endpoint for the same user will return an error since the email is already verified. A wrong, expired or already-used code returns a `400` with `"invalid or expired otp provided"`. After **5 wrong codes**, the code is cancelled and the API returns `"too many invalid attempts, please request a new otp"` — send a new code to continue. {% endstep %} {% endstepper %} ### Verify a user's phone number *** Phone verification works exactly like email verification, but the code is delivered via SMS instead. {% stepper %} {% step %} #### Send the verification code ```http GET /api/v1/user/phone-verification/send/:user_id ``` Tendar sends a 6-digit code to the user's phone number. The code expires after **10 minutes**. **Response** ```json { "error": false, "message": "Phone verification token sent successfully" } ``` > The user must have a phone number on file. If the `phone` field is empty, the API returns a `400` error with the message `"phone number not found for this user"`. > {% endstep %} {% step %} #### Submit the code ```http POST /api/v1/user/phone-verification/verify/:user_id ``` **Request body** ```json { "token": "198694" } ``` **Response** ```json { "error": false, "message": "Phone verified successfully" } ``` Once verified, the user's `phone_verified` field flips to `true`. Wrong codes behave exactly as for email verification: `"invalid or expired otp provided"`, and the code is cancelled after 5 wrong attempts. > **Billing note:** Both email and phone verification OTPs are billable based on your subscription's pricing plan (email OTP and SMS OTP are priced separately). If the code cannot be sent — for example, your wallet balance is insufficient — the send endpoint returns the error and no code is issued. > {% endstep %} > {% endstepper %} ### Fetch a user *** You can retrieve a single user by their `user_id` or `email`. This is useful for displaying user details in your dashboard, or for confirming a user exists before performing other operations. ```http GET /api/v1/user/fetch/:email_or_id ``` The `:email_or_id` parameter is flexible — pass the user's email address, their `user_id`, or their internal Tendar `id`. **Example — fetch by user ID:** ```http GET /api/v1/user/fetch/usr-lyfriztafj ``` **Example — fetch by email:** ```http GET /api/v1/user/fetch/johndoe@example.com ``` **Response** `200 OK` ```json { "data": { "id": "67ad212f3d5b0234cbb53527", "user_id": "usr-lyfriztafj", "first_name": "John", "last_name": "Doe", "email": "johndoe@example.com", "phone": "+2348012345678", "date_of_birth": "01/01/1990", "gender": "male", "country": "nigeria", "state": "lagos", "city": "ikeja", "country_code": "NG", "email_verified": true, "phone_verified": false, "active": true, "role": "customer", "age": 35, "metadata": {}, "created_at": "2025-02-12T22:31:11.619Z", "updated_at": "2025-02-12T22:31:11.619Z" }, "error": false, "message": "User fetched successfully" } ``` If no user is found, the API responds with a `404` and the message `"user not found"`. ### List users *** When you need to display a table of users in your dashboard or search through your user base, the list endpoint gives you paginated results with powerful filtering and sorting. ```http GET /api/v1/user/list ``` ### Query parameters | Parameter | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | integer | Page number. Defaults to `1`. | | `limit` | integer | Number of results per page. Defaults to `50`, maximum `1000`. | | `search` | string | Free-text search across `user_id`, `first_name`, `last_name`, `middle_name`, `email` and `phone`. Every word must match (case-insensitive). | | `id` | string | Filter by the internal Tendar `id`. | | `user_id` | string | Filter by `user_id`. | | `active` | boolean | Filter by active status (`true` or `false`). | | `role` | string | Filter by role. | | `country` | string | Filter by country. | | `email_verified` | boolean | Filter by email verification status. | | `phone_verified` | boolean | Filter by phone verification status. | | `age` | number | A single value (`30`) or an inclusive range (`25/35`). | | `years_of_employment` | number | A single value (`5`) or an inclusive range (`2/10`). | | `metadata.` | string | Exact match on a key inside `metadata`, e.g. `metadata.segment=gold`. | | `created_at` | string | A single day (`15-03-2024`) or a range (`01-03-2024/29-03-2024`) in `DD-MM-YYYY` format. The end date is inclusive. | | `date_by` | string | A `created_at` shortcut: `today`, `yesterday`, `this_week`, `last_week`, `this_month`, `last_month`, `this_year`, `last_year`. Overrides `created_at`. | | `sort-` | string | Sort by `created_at`, `updated_at`, `first_name` or `last_name` (e.g. `sort-first_name=asc`). `asc` for ascending, anything else for descending. Defaults to newest first. | See [Query Params](/documentation/getting-started/query-params.md) for the full filtering grammar. **Example — list active customers, page 1, 20 per page, sorted newest first:** ```http GET /api/v1/user/list?page=1&limit=20&active=true&sort-created_at=desc ``` **Response** `200 OK` ```json { "data": { "total": 142, "page": 1, "per_page": 20, "prev": 0, "next": 2, "total_page": 8, "docs": [ { "user_id": "usr-lyfriztafj", "first_name": "John", "last_name": "Doe", "email": "johndoe@example.com", "active": true, "..." } ] }, "error": false, "message": "Users fetched successfully" } ``` The `docs` array contains the user objects for the current page. Use the `next` field to determine if there are more pages — a value of `0` means you're on the last page. ### Edit a user *** User profiles change over time — people move, change phone numbers, or update their employment status. The edit endpoint lets you update any combination of fields in a single request. Only include the fields you want to change; everything else stays as-is. ```http PUT /api/v1/user/edit/:user_id ``` **Request body** — only the fields you want to update: ```json { "first_name": "John", "last_name": "Doe", "middle_name": "Michael", "phone": "+2348012345678", "employment_status": "self-employed", "metadata": { "internal_tier": "gold" } } ``` You can update any of these fields: `user_id`, `first_name`, `last_name`, `middle_name`, `email`, `phone`, `date_of_birth`, `gender`, `address`, `country`, `state`, `city`, `image`, `employment_status`, `years_of_employment`, `active`, `email_verified`, `phone_verified` and `metadata`. The same format rules as [Create a user](#create-a-user) apply. **A few things to know:** * **Email uniqueness** — If you update the `email` field, Tendar checks that no other user under your company already uses that email. If one does, you'll get a `400` with `"email already exists"`. * **Changing the `user_id`** — Send a new `user_id` to re-key the user (the URL still uses the current one). It cannot be empty, and if another user already has it the API returns a `400` with `"user already exists"`. * **Verification flags** — `email_verified` and `phone_verified` can be set directly, for example when you have already verified the contact details on your own platform. * **`metadata`** — The object you send replaces the stored one. * **Auto-recomputed fields** — If you update `date_of_birth`, the `age` field is recalculated. If you update `country`, the `country_code` is re-derived. * **User not found** — If the `user_id` doesn't match any user under your company, the API returns a `404`. **Response** `200 OK` ```json { "data": { "user_id": "usr-lyfriztafj", "first_name": "John", "last_name": "Doe", "middle_name": "Michael", "employment_status": "self-employed", "metadata": { "internal_tier": "gold" }, "..." }, "error": false, "message": "User updated successfully" } ``` ### Bulk create users *** If you're migrating an existing user base into Tendar, or you need to onboard a batch of customers at once, the bulk create endpoint lets you create up to **1,000 users** in a single request. ```http POST /api/v1/user/bulk/create ``` #### Option 1 — JSON body Send an array of user objects in the request body: ```json { "users": [ { "first_name": "John", "last_name": "Doe", "email": "johndoe+1@example.com", "phone": "+2348012345678", "date_of_birth": "01/01/1990", "gender": "male", "country": "nigeria", "state": "lagos", "city": "ikeja", "address": "No 1, John Doe Street", "employment_status": "employed", "active": true, "metadata": {} }, { "first_name": "Jane", "last_name": "Smith", "email": "janesmith@example.com", "phone": "+2349087654321", "date_of_birth": "15/06/1995", "gender": "female", "country": "nigeria", "state": "abuja", "city": "garki", "address": "Plot 5, Garki Area", "employment_status": "self-employed", "active": true, "metadata": {} } ] } ``` #### Option 2 — CSV upload You can also upload a CSV file using `multipart/form-data`. The file should be attached under the field name `csv`. To see the expected column format, download the [sample CSV](#download-a-sample-csv) first. #### How bulk creation works 1. Tendar validates every user in the batch first. The batch must contain between 1 and 1,000 users, and every row must pass the same checks as [Create a user](#create-a-user). **If any row is invalid, the whole batch is rejected** with a `400` naming the problem, and nothing is created. 2. Users whose email or `user_id` already exist in your account are **silently skipped** — they won't cause the batch to fail. A row that repeats the email or `user_id` of an earlier row in the same batch is skipped too. 3. The new users are created together, as customers. 4. The request returns once the import has finished — there is nothing to poll. > **Billing:** Each new user created is charged individually based on your plan's `customer.create` pricing. If your batch has 500 users but 100 already exist, you're only billed for the 400 new ones. If your wallet cannot cover the new users, the request fails and nothing is created. **Response** `200 OK` ```json { "error": false, "message": "Users created successfully" } ``` > Only one bulk import can run at a time for your company. If another import is still running, the API returns a `400` error with the message `"upload is processing"` — retry once it finishes. ### Export users *** Need to pull your user data into a spreadsheet or feed it into another system? The export endpoint generates a CSV file, uploads it to cloud storage, and returns a temporary download link. ```http GET /api/v1/user/export ``` ### Query parameters The export accepts every filter and sort of the [list endpoint](#list-users) (`search`, `active`, `role`, `country`, `email_verified`, `phone_verified`, `age`, `years_of_employment`, `metadata.`, `created_at`, `date_by`, `sort-` …). It is not paginated; instead: | Parameter | Type | Description | | --------- | ------- | ------------------------------------------------------------------------- | | `limit` | integer | Maximum number of users to export. Omit it to export every matching user. | **Example — export all active users created in March 2024:** ```http GET /api/v1/user/export?active=true&created_at=01-03-2024/31-03-2024 ``` **Response** `200 OK` ```json { "data": { "path": "https://tendar.s3.us-east-2.amazonaws.com/yourcompany_users_1719362941", "expires_at": "2025-02-12T22:50:01.756Z" }, "error": false, "message": "Users exported successfully" } ``` The `path` is a private, pre-signed URL that you can use to download the CSV file. It's temporary — the link is valid for **15 minutes**, and the `expires_at` timestamp tells you exactly when it stops working. Request a new export if it expires. The exported CSV includes these columns: `user_id`, `first_name`, `last_name`, `middle_name`, `email`, `phone`, `date_of_birth`, `gender`, `address`, `country`, `state`, `city`, `country_code`, `image`, `employment_states`, `years_of_employment`, `email_verified`, `phone_verified`, `active`, `age`, `metadata`, `created_at`, `updated_at` A few formatting details, so your import scripts parse the file correctly: * The employment status column is headed **`employment_states`** (kept for compatibility with existing spreadsheets); it holds the user's `employment_status`. * Phone numbers are prefixed with an apostrophe (`'+2348012345678`) so spreadsheet tools keep them as text. * `metadata` is a JSON string. * `created_at` and `updated_at` look like `Feb 12, 2025 22:31:11 UTC`. ### Download a sample CSV *** If you plan to use the CSV upload option for bulk creation, start by downloading the sample template. It shows you exactly which columns are expected and includes an example row. ```http GET /api/v1/user/sample-csv ``` **Response** `200 OK` ```json { "data": { "path": "https://tendar.s3.us-east-2.amazonaws.com/sample_users_1719362952", "expires_at": "2025-02-12T22:50:12.818Z" }, "error": false, "message": "Sample csv fetched successfully" } ``` The sample CSV contains these columns: `user_id`, `first_name`, `last_name`, `middle_name`, `email`, `phone`, `date_of_birth`, `gender`, `image`, `country`, `state`, `city`, `address`, `employment_status`, `active` Fill in your data following the same format and upload it via the [bulk create](#bulk-create-users) endpoint. ### Putting it all together *** A typical onboarding integration follows this flow: ``` 1. Create user ──▶ 2. Verify email ──▶ 3. Verify phone ──▶ 4. Run KYC ──▶ 5. Ready │ │ │ ▼ │ (BVN, NIN, etc.) ▼ User exists in Tendar system ``` Here's how that looks end-to-end in code: ```bash # 1. Create the user curl -X POST {{base_url}}/api/v1/user/create \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Amina", "last_name": "Bello", "email": "amina.bello@example.com", "phone": "+2348099887766", "date_of_birth": "22/03/1995", "gender": "female", "country": "nigeria", "state": "abuja", "city": "wuse", "address": "12 Wuse Zone 3, Abuja", "employment_status": "employed", "active": true, "metadata": { "source": "mobile_app" } }' # Save the returned user_id — e.g. "usr-abcxyz1234" # 2. Send email verification curl -X GET {{base_url}}/api/v1/user/email-verification/send/usr-abcxyz1234 \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" # 3. User receives the code and enters it in your app curl -X POST {{base_url}}/api/v1/user/email-verification/verify/usr-abcxyz1234 \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "token": "583921" }' # 4. Send phone verification curl -X GET {{base_url}}/api/v1/user/phone-verification/send/usr-abcxyz1234 \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" # 5. User receives the SMS code and enters it in your app curl -X POST {{base_url}}/api/v1/user/phone-verification/verify/usr-abcxyz1234 \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "token": "174582" }' # The user is now fully onboarded and ready for KYC, credit scoring, loans, etc. ``` ### Error handling *** User endpoints can return several types of errors. Here are the most common: | Scenario | HTTP Status | Message | | ---------------------------------------------------------- | ----------- | ------------------------------------------------------- | | User with the given `user_id` already exists | 400 | `"user already exists"` | | Email already in use by another user (on edit) | 400 | `"email already exists"` | | `role` other than `customer` on create | 400 | `"the role field must be one of customer"` | | Email verification requested but email is already verified | 400 | `"email already verified"` | | Email verification requested but user has no email | 400 | `"email address not found for this user"` | | Phone verification requested but phone is already verified | 400 | `"phone already verified"` | | Phone verification requested but user has no phone number | 400 | `"phone number not found for this user"` | | Wrong, expired or already-used verification code | 400 | `"invalid or expired otp provided"` | | Too many wrong verification codes (5) | 400 | `"too many invalid attempts, please request a new otp"` | | A bulk import is already running | 400 | `"upload is processing"` | | CSV upload without the `csv` field | 400 | `"the csv field is required"` | | Uploaded file is not a CSV during bulk import | 400 | `"invalid file type, only csv files are allowed"` | | Bulk batch with more than 1,000 users | 400 | `"the users field must be at most 1000"` | | Insufficient wallet balance | 400 | `"insufficient balance, please top up your wallet."` | | Missing or invalid field | 400 | Names the field, e.g. `"the email field is required"` | | User not found (invalid `user_id` or email) | 404 | `"user not found"` | All errors follow the standard Tendar error format: ```json { "error": true, "message": "A description of what went wrong" } ``` ### Next steps *** Now that your users are created and verified, you're ready to explore the rest of the Onboarding Service: * [OTP](/documentation/onboarding/one-time-password.md) — Send custom one-time passwords for transaction confirmations or any verification flow. * [KYC](/documentation/onboarding/know-your-customer.md) — Identity Verification — Verify user identities against BVN, NIN, driver's license, passport, and more. * [UID Management](/documentation/onboarding/know-your-customer.md#uid-management) — Manage and verify identity documents after a KYC lookup. Explore other Tendar services: * [**Credit Score Service**](/documentation/credit-scoring/editor.md) — Calculate risk scores and credit reports for your users. * [**Disbursement Service**](/documentation/disbursement/disbursement.md) — Create and manage loans, disburse funds, and track repayments. * [**Recollection Service**](/documentation/recollection/recollection.md) — Automate repayment collection from your borrowers. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tendar.co/documentation/onboarding/user-management.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.