# Introduction

This section serves as a comprehensive guide detailing the most common and impactful business workflows that are fully supported and enabled by Jiko's robust suite of APIs. Our primary goal is to empower our customers by providing clear, actionable insights into how they can integrate and utilize Jiko's technology to streamline their operations, enhance their product offerings, and improve their overall efficiency.
The following sections describe these core business workflows and identify the corresponding API endpoints and sequence that our customers will utilize.
By outlining these use cases and their associated endpoints, we aim to facilitate rapid integration, minimize development time, and ensure that our customers can quickly realize the full potential and value of partnering with Jiko.

Note: this documentation focuses specifically on Jiko's Customer APIs, which are distinct from Jiko's Partner APIs (used by Jiko's partners to manage funds and payments on behalf of their own customers).

# Manage Users & Access

## List Users with their Active status and Role

### Business Goal

Provide a list of all users associated with the organization, enabling administrators and operational teams to understand who has access to the platform, each user's role, and whether their access is active. Information about the user creation date and last login activity also support access governance and security reviews.

### Business Workflow Example

Customer systems:

1. Retrieve from Jiko the list of users associated with the customer organization.
2. Review each user's active status, role, and access level to ensure alignment with internal policies.
3. Trigger follow-up actions in internal systems, such as access reviews, offboarding workflows, or permission changes.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | List of all users (team members). | GET [`/api/v1/team/`](/products/customer-api/reference/team/get_team_api_v1_team__get) |
| 1b | Retrieve the details of a specific user (team member), whose Jiko ID is passed as filtering parameter. | GET [`/api/v1/team/{member_id}/`](/products/customer-api/reference/team/get_team_member_api_v1_team__member_id___get) |


### Illustration


```json
{
  "member_id": "bede86ae-6b9d-4039-ac81-ba53302606ac",
  "last_login": "2025-12-26T14:38:22.210507",
  "first_name": "John",
  "last_name": "Doe",
  "email": "jdoe@gmail.com",
  "role": "ADMINISTRATOR",
  "status": "ACTIVE",
  "added_date": "2025-08-28T17:43:19.287013",
  "deactivated_date": null,
  "phone_number": "+33671915834",
  "user_id": "3b4f3fd4-1d59-4264-9350-5665bdac5d79"
},
```

## Invite a User

### Business Goal

Allow internal identity or operational systems of the customer organization to programmatically invite new users to access the Jiko platform with a defined role (Viewer, Market, Checker, Non-transactional Admin, Admin). Where a new user is identified through a name, email, and phone number.

The invitee will receive an invitation email and will need to click it to complete the user registration. By this time, the user status remains `PENDING`.

### Business Workflow Example

Customer systems:

1. Collect the new user's name, email address, phone number, and intended role through an internal system or admin interface.
2. Call Jiko's user invitation endpoint with the user information and assigned role.
3. Get Jiko's user list to view the newly invited user and its Jiko member id.
4. Track the invitation status from internal systems for onboarding and audit purposes.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Generate a user invitation for a given role. This user is created with a `PENDING` status. | POST [`/api/v1/team/invite/`](/products/customer-api/reference/team/invite_team_member_api_v1_team_invite__post) |
| 2 | Get the list of all users, to get the Jiko `member_id` of the newly invited user. | GET [`/api/v1/team/`](/products/customer-api/reference/team/get_team_api_v1_team__get) |
| 3 | Monitor the `status` of the invitee, using its Jiko `member_id` as filtering parameter. The status becomes `ACTIVE` once the user completes the invitation. | GET [`/api/v1/team/{member_id}/`](/products/customer-api/reference/team/get_team_member_api_v1_team__member_id___get) |


### Illustration


```json
{
 "first_name": "John",
 "last_name": "Doe",
 "email": "jdoe@domain.com",
 "phone_number": "+111111111111",
 "role": "VIEWER"
}
```

## Resend a User invitation

### Business Goal

Resend an invitation to a user who has been invited but has not yet completed registration. To ensure that pending invitees receive timely reminders and can activate their accounts without administrative delays.

### Business Workflow Example

Customer systems:

1. Track the invitation status.
2. If an invited user is still in status `PENDING` after a given delay, call Jiko's to resend the invitation.
3. Track the invitation status.
4. Update internal systems when the user completed registration.
5. Or alternatively cancel the invitation: see [Cancel a User invitation](#cancel-a-user-invitation).


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Resend an invitation to a user. | POST [`/api/v1/team/{member_id}/invite/`](/products/customer-api/reference/team/resend_invite_team_member_api_v1_team__member_id__invite__post) |


## Cancel a User invitation

### Business Goal

Enabling administrators to revoke invitations that are no longer valid, such as for incorrect, duplicate, or obsolete user entries.

### Business Workflow Example

Customer systems:

1. Receive the request from internal systems to revoke an invitation, or automatically revoke it after a predefined delay after which the user has not completed registration.
2. Call Jiko's to cancel the invitation for this user.
3. Call Jiko to confirm that this user is no longer listed in the user list.
4. Update internal systems to record the successful invitation revocation.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Cancel the invitation. | DELETE [`/api/v1/team/{member_id}/invite/`](/products/customer-api/reference/team/cancel_invite_team_member_api_v1_team__member_id__invite__delete) |


## Modify the Role of a User and/or Reactivate a User

### Business Goal

Enable administrators to adjust permissions and/or reinstate access for a previously deactivated user.

Note: the deactivation of a user is handled through DELETE [`/api/v1/team/{member_id}/`](/products/customer-api/reference/team/deactivate_team_member_api_v1_team__member_id___delete).

### Business Workflow Example

Customer systems:

1. Collect the new user's role or the request to reactivate a user.
2. Call Jiko's to edit the role of a specific user, or reactivate a specific user, or both.
3. Get Jiko's confirmation with the resulting user's role and status.
4. Propagate the information to internal systems.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Get the list of users and retrieve the `member_id` of the user to modify. | GET [`/api/v1/team/`](/products/customer-api/reference/team/get_team_api_v1_team__get) |
| 2 | Modify a specific user. Use-cases:  • To only change the role, use field `role` only.  • To only reactivate a user, use field `status` only.  • To change the role and reactivate a user, use fields `role` and `status`. | PUT [`/api/v1/team/{member_id}/`](/products/customer-api/reference/team/edit_team_member_api_v1_team__member_id___put) |


### Illustration


```json
{
 "role": "CHECKER",
 "status": "ACTIVE"
}
```

## Check when a User Last Logged in

### Business Goal

Support security and access governance by enabling administrators to get the last login date and time of a specific user.

### Business Workflow Example

Customer systems:

1. Receive the request from an internal system to display or verify the last login date/time of a user.
2. Get from Jiko the `member_id` of this user, if not already known by internal systems.
3. Call Jiko's endpoint with this user identifier.
4. Pass the received lost login date and time to internal systems.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Get the list of users and retrieve the `member_id` of the user to deactivate. | GET [`/api/v1/team/`](/products/customer-api/reference/team/get_team_api_v1_team__get) |
| 2 | Get the `last_login` date and time. | GET [`/api/v1/team/{member_id}/`](/products/customer-api/reference/team/get_team_member_api_v1_team__member_id___get) |


### Illustration


```json
{
   "member_id": "e3804cea-7790-4538-a483-f44c1c93a123",
   "email": "userabc@domain.com",
   "first_name": "a",
   "last_name": "bc",
   "role": "ADMINISTRATOR",
   "status": "ACTIVE",
   "added_date": "2025-09-30T17:36:03.807715",
   "last_login": "2025-12-26T10:41:53.539650",
   "deactivated_date": null,
   "team_id": "0b5b74f5-ad65-4c6d-9170-60fe29794z55",
   "partner_id": "2d9800f1-5d25-43d1-bbfd-90e3cd1cdfvg",
   "user_id": "f0cc703e-825c-47c5-a8bf-febe516e12ce",
   "phone_number": "+1222222222"
}
```

## Deactivate a User

### Business Goal

Support security and access governance by enabling administrators to promptly revoke permissions when a user leaves the organization, changes roles, or no longer requires access.

### Business Workflow Example

Customer systems:

1. Receive the request from internal systems to deactivate a user.
2. Get from Jiko the `member_id` of this user, if not already known by internal systems.
3. Call Jiko's user deactivation endpoint with this user identifier.
4. Confirm the user's status has been updated to inactive in Jiko.
5. Log the deactivation action in internal systems for audit and compliance purposes.
6. Notify relevant teams or systems, if required, that the user no longer has access.
7. Review periodically to ensure deactivated users remain inactive.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Get the list of users and retrieve the `member_id` of the user to deactivate. | GET [`/api/v1/team/`](/products/customer-api/reference/team/get_team_api_v1_team__get) |
| 2 | Request to deactivate the user and receive user details with its update `status` in the response. | DELETE [`/api/v1/team/{member_id}/`](/products/customer-api/reference/team/deactivate_team_member_api_v1_team__member_id___delete) |
| 3 | If needed, periodically ensure this user is inactive. | GET [`/api/v1/team/{member_id}/`](/products/customer-api/reference/team/get_team_member_api_v1_team__member_id___get) |


### Illustration

DELETE `/api/v1/team/e3804cea-7790-4538-a483-f44c1c93a005/`

## Retrieve User Audit logs

### Business Goal

Expose a chronological record of user events - such as logins, data listing, data creation/modification... - for accountability, access governance, and internal investigations. Including the connection IP address and user agent data.

Examples of events:

- `team_member.invite`
- `team_member.modify`
- `team_member.reactivate`
- `pocket.list`
- `pocket.modify`
- `transaction.list`


### Business Workflow Example

Customer systems:

1. Select the specific user whose activity needs to be reviewed.
2. Call the Jiko user audit log endpoint with the user identifier and date/time range filter.
3. Retrieve from Jiko the chronological list of user events.
4. Analyze the events to monitor activity, detect anomalies, or validate compliance with internal policies.
5. Store or integrate the audit data into internal reporting, monitoring, or security systems.
6. Follow up on flagged events with appropriate operational or security actions.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Get the list of users and retrieve the `member_id` of the user whose audit log must be queried. | GET [`/api/v1/team/`](/products/customer-api/reference/team/get_team_api_v1_team__get) |
| 2 | Query the audit log of this user, filtered by from/to timestamps. | GET [`/api/v1/team/members/{member_id}/audit-logs/`](/products/customer-api/reference/team/get_team_member_audit_logs_api_v1_team_members__member_id__audit_logs__get) |


### Illustration


```json
{
  "actor": "3b4f3fd4-1d59-4264-9350-5665bdac5d22",
  "event_name": "pocket.modify",
  "id": "79214153-a9b1-4325-b2b4-20efe964c165",
  "entry_metadata": {
      "ip_address": "86.241.152.204",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
      "token_hash": "iYx2Vi25n2YwUlZPmVLjTTdpQ76NuqE3vVP06p_Ivuo=",
      "pocket_id": "744ab7f4-e94f-433b-9224-01cbe6585c22"
  },
  "team_id": "1b5b74f5-af65-4c6d-9170-60fe29794b38",
  "timestamp": "2025-12-26T16:55:02.771046"
}
```