User Management APIs

Comprehensive documentation for the EdfaPay User Management APIs, covering user creation, invitations, profile updates, user retrieval, search, pagination, and deletion. Includes endpoint references, authentication requirements, access control, request structures, response formats, and integration guidelines.

Overview

The EdfaPay User Management APIs provide a centralized interface for managing user accounts across the EdfaPay platform. These APIs support user creation, invitations, profile updates, user retrieval, searching, and deletion.

This documentation is intended for developers and authorized platform administrators integrating with or managing user-related functionality within EdfaPay.

API Capabilities

The User Management API collection includes the following operations:

APIMethodEndpointDescription
Create UserPOST/api/v1/users/userCreates a new user account.
Update UserPUT/api/v1/users/userUpdates an existing user account.
Invite UserPOST/api/v1/users/invite-userInvites a new user to the platform.
Get User DetailsGET/api/v1/users/user/USERIDRetrieves a user by their unique ID.
Search UsersGET/api/v1/users/searchSearches and retrieves users using pagination and search criteria.
Delete UserDELETE/api/v1/users/user/USERIDDeletes an existing user by ID.
Delete Multiple UsersPATCH/api/v1/users/batch-deleteDeletes multiple users in a single request.

Environment and Base URL

All endpoints documented in this section use the EdfaPay API base URL.

Production Base URL

https://app-api.edfapay.com

The complete request URL is formed by appending the endpoint path to the base URL.

For example:

https://app-api.edfapay.com/api/v1/users/user

Authentication

Requests must include a valid EdfaPay API key in the X-API-KEY HTTP header.

Required Headers

X-API-KEY: YOUR_API_KEY
Accept: */*

For endpoints that accept a JSON request body, include:

Content-Type: application/json

Replace YOUR_API_KEY with the API key authorized for the target environment.

Access Control and Permissions

The documented User Management endpoints specify access levels from the following list, depending on the operation:

  • SUPER_ADMIN
  • PARTNER
  • MERCHANT
  • BRANCH

Access is endpoint-specific. An access level listed for one operation should not be assumed to apply to every operation in this collection.

Before making a request, review the relevant endpoint documentation to confirm the required access level and any applicable permissions.

User Data Model

The documented create and update request examples use the following user-related fields:

FieldTypeDescription
idUUID stringUser identifier included in the update request.
emailStringUser's email address; included in create and invitation requests.
businessUnitIdUUID stringBusiness unit identifier included in create and invitation requests.
firstNameStringUser's first name.
lastNameStringUser's last name.
phoneNumberStringUser's phone number.
userTypeString / enumUser type, represented in the examples by values such as SUPER_ADMIN.
rolesArray of stringsRoles associated with the user.
permissionsArray of stringsPermissions associated with the user.
imageUrlStringImage URL included in the update request.
holderAccountIdNumberHolder account identifier included in create, update, and invitation request examples.

Important: The fields shown above are based on the available Swagger examples. Requiredness, validation rules, supported enum values, and field behavior should be confirmed in the schema for each individual endpoint.

API Operations

1. Create User

Creates a new user account.

POST /api/v1/users/user

The request body includes user information such as the email address, business unit, roles, permissions, user type, phone number, name, and holder account identifier.

2. Update User

Updates an existing user account.

PUT /api/v1/users/user

The request body includes the user ID and the user fields supported by the endpoint.

3. Invite User

Initiates an invitation for a new user.

POST /api/v1/users/invite-user

The request body includes the user's email address, business unit, roles, permissions, user type, phone number, first name, last name, and holder account identifier.

4. Get User Details

Retrieves user details using the user's unique identifier.

GET /api/v1/users/user/USERID

Path parameter

ParameterTypeRequiredDescription
userIdUUID stringYesUnique identifier of the user to retrieve.

5. Search Users

Searches for users using pagination and search criteria.

GET /api/v1/users/search

The endpoint defines two required query objects:

  • pageProperties — Pagination settings, including pageNumber and pageSize.
  • searchCriteria — Search filters, including text and active.

The query objects' exact URL serialization should be taken from Swagger's Try it out output rather than assuming a particular query-string format.

6. Delete User

Deletes an existing user using the user's unique identifier.

DELETE /api/v1/users/user/USERID

Path parameter

ParameterTypeRequiredDescription
userIdUUID stringYesUnique identifier of the user to delete.

7. Delete Multiple Users

Deletes multiple users in a single request.

PATCH /api/v1/users/batch-delete

The request body is an array of user ID strings:

[
  "3fa85f64-5717-4562-b3fc-2c963f66afa6"
]

Provide the identifiers of the users targeted by the operation.

Standard Response Structure

The documented endpoints use the following example response envelope:

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {}
}
FieldTypeDescription
codeNumberResponse code returned in the response body.
messageStringResponse message.
errorCodeStringError code field.
dataObjectEndpoint-specific response data.

The actual contents of data depend on the operation. For the Search Users endpoint, the documented data structure includes pagination metadata and a collection of results.

Pagination

The Search Users endpoint documents a paginated response containing fields such as:

FieldDescription
totalPagesTotal number of available pages.
totalElementsTotal number of matching elements.
sizePage size reported by the response.
contentCollection of matching records.
numberCurrent page number reported by the response.
numberOfElementsNumber of elements in the current page.
firstIndicates whether the current page is the first page.
lastIndicates whether the current page is the last page.
emptyIndicates whether the current page contains no results.
pageablePagination and sorting metadata.
sortSorting metadata.

The content item schema should be consulted in the API specification for the actual user record fields.

HTTP Status Codes

The Swagger documentation shown for these endpoints lists the following responses:

HTTP StatusDescription
200 OKThe request was processed successfully at the HTTP level.
400 Bad RequestThe request could not be processed as submitted.

Refer to the individual endpoint response definitions for the response body and any additional documented status codes.

Integration Guidelines

  1. Authenticate every request. Include the required X-API-KEY header.
  2. Use the correct environment. Ensure the API key and base URL correspond to the intended environment.
  3. Validate identifiers. Use valid UUID values for fields and path parameters defined as UUIDs.
  4. Respect access control. Verify that the authenticated user has the access level required by the endpoint.
  5. Follow the endpoint schema. Send the request body and query parameters in the format defined by Swagger.
  6. Handle errors appropriately. Check both the HTTP status and the response body when processing API results.
  7. Use deletion operations carefully. Confirm the target user IDs before submitting single-user or bulk deletion requests.

Endpoint Reference

For detailed request schemas, parameter definitions, response examples, and interactive testing, refer to the individual API pages listed under User Management APIs in the EdfaPay API documentation.


Did this page help you?