Skip to main content

👥 People API

The People API allows you to manage contacts and people within Pika. This includes family members, roommates, business contacts, and anyone else you want to track in relation to your financial transactions. People can be associated with transactions for shared expenses, gifts, loans, and other financial interactions.

📡 Base URL​

All people endpoints are prefixed with:

/wp-json/pika/v1/people

🚀 Endpoints​

Get All People​

Retrieve all people for the authenticated user.

Endpoint: GET /wp-json/pika/v1/people

Headers:

  • Cookie: Authentication cookie

Response:

[
    {
        "id": "7",
        "name": "Lena",
        "description": "Aunty",
        "email": "",
        "phone": "",
        "avatar": null,
        "lastTransactionAt": "2025-08-03 03:38:37",
        "totalTransactions": "5",
        "balance": "0.0000"
    },
    {
        "id": "8",
        "name": "Anas",
        "description": "Friend",
        "email": "anasanas865oo@gmail.com",
        "phone": "+918590608192",
        "avatar": {
            "id": "4",
            "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/person-688b93a8b8b3c-89829934.jpg",
            "type": "image",
            "name": "1000118841.jpg",
            "size": "27750"
        },
        "lastTransactionAt": "2025-07-30 05:50:00",
        "totalTransactions": "1",
        "balance": "-2500.0000"
    },
    {
        "id": "2",
        "name": "Bob",
        "description": "Brother",
        "email": "",
        "phone": "",
        "avatar": null,
        "lastTransactionAt": "2025-07-29 03:05:00",
        "totalTransactions": "1",
        "balance": "-300.0000"
    },
    {
        "id": "6",
        "name": "Vishnu",
        "description": "Friend",
        "email": "",
        "phone": "+919876543210",
        "avatar": {
            "id": "5",
            "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/person-688b9491272ce-099878293.jpg",
            "type": "image",
            "name": "1000118842.jpg",
            "size": "42110"
        },
        "lastTransactionAt": "2025-07-31 11:10:00",
        "totalTransactions": "3",
        "balance": "0.0000"
    }
]

Example Request:

curl -X GET "http://localhost:8000/wp-json/pika/v1/people" \
  -H "Cookie: pika_token=token"

Get Person by ID​

Retrieve a specific person by their ID.

Endpoint: GET /wp-json/pika/v1/people/{id}

Headers:

  • Cookie: Authentication cookie

Response:

{
    "id": "8",
    "name": "Bob",
    "description": "Friend",
    "email": "bob@gmail.com",
    "phone": "",
    "avatar": {
        "id": "4",
        "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/person-688b93a8b8b3c-90038308.jpg",
        "type": "image",
        "name": "10004948841.jpg",
        "size": "27750"
    },
    "lastTransactionAt": "2025-07-30 05:50:00",
    "totalTransactions": "1",
    "balance": "-2500.0000",
    "totalSummary": {
        "totalSpent": "2500.0000",
        "totalReceived": "0.0000"
    }
}

Example Request:

curl -X GET http://localhost:8000/wp-json/pika/v1/people/8 \
  -H "Cookie: pika_token=token"

Create Person​

Create a new person.

Endpoint: POST /wp-json/pika/v1/people

Headers:

  • Cookie: Authentication cookie
  • Content-Type: application/json

Request Body:

{
    "name":"Jack",
    "email":"",
    "phone":"",
    "avatarId":"",
    "description":"Gymmate"
}

Required Fields:

  • name (string): Person's full name

Optional Fields:

  • email (string): Email address
  • phone (string): Phone number
  • avatarId (integer): Avatar image ID
  • description (string): Description like relationship

Response:

{
    "id": "11",
    "user_id": "2",
    "name": "Jack",
    "email": "",
    "phone": "",
    "avatar_id": null,
    "description": "Gymmate",
    "is_active": "1",
    "created_at": "2025-09-02 03:49:19",
    "updated_at": "2025-09-02 03:49:19"
}

Example Request:

curl -X POST http://localhost:8000/wp-json/pika/v1/people \
  -H "Cookie: pika_token=token" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Jack",
    "email":"",
    "phone":"",
    "avatarId":"",
    "description":"Gymmate"
  }'

Update Person​

Update an existing person.

Endpoint: PUT /wp-json/pika/v1/people/{id}

Headers:

  • Cookie: Authentication cookie
  • Content-Type: application/json

Request Body:

{
  "name":"Jack",
  "email":"",
  "phone":"",
  "avatarId":"14",
  "description":"Old Gymmate"
}

Response:

{
    "id": "11",
    "name": "Jack",
    "description": "Old Gymmate",
    "email": "",
    "phone": "",
    "avatar": {
        "id": "14",
        "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/person-68b66a0d774a2-1756785165.jpg",
        "type": "image",
        "name": "avatar.jpg",
        "size": "87265"
    },
    "lastTransactionAt": null,
    "totalTransactions": "0",
    "balance": "0.0000"
}

Example Request:

curl -X PUT http://localhost:8000/wp-json/pika/v1/people/14 \
  -H "Cookie: pika_token=token" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Jack",
    "email":"",
    "phone":"",
    "avatarId":"14",
    "description":"Old Gymmate"
  }'

Delete Person​

Delete a person. People with transactions cannot be deleted.

Endpoint: DELETE /wp-json/pika/v1/people/{id}

Headers:

  • Cookie: Authentication cookie

Response:

{"message":"Person deleted successfully"}

Example Request:

curl -X DELETE http://localhost:8000/wp-json/pika/v1/people/14 \
  -H "Cookie: pika_token=token"

🚨 Error Responses​

Person Not Found​

This error is returned when an operation is requested on a person's record that does not exist.

{
  "code": "person_not_found",
  "message": "Person not found",
  "data": {
    "status": 404
  }
}

Invalid Person Name​

This response is used when the provided name for a person does not meet validation criteria (e.g., it is empty or too long).

{
  "code": "invalid_name",
  "message": "Invalid person name",
  "data": {
    "status": 400
  }
}

Invalid Avatar ID​

This error indicates that the avatar_id provided does not correspond to a valid, existing avatar in the system.

{
  "code": "invalid_avatar",
  "message": "Invalid avatar id",
  "data": {
    "status": 400
  }
}

Invalid Email​

This error is triggered when the email address provided for a person is not in a valid format (e.g., missing '@' or a domain).

{
  "code": "invalid_email",
  "message": "Invalid email",
  "data": {
    "status": 400
  }
}

Person Already Exists​

This error occurs when attempting to create a person with a name and email combination that already exists, preventing duplicates.

{
  "code": "person_already_exists",
  "message": "Person with same name and email already exists",
  "data": {
    "status": 400
  }
}

Person Has Transactions​

This error prevents the deletion of a person who is linked to one or more financial transactions. The associated transactions must be removed first.

{
  "code": "person_has_transactions",
  "message": "Person has transactions. Please delete the transactions first.",
  "data": {
    "status": 400
  }
}

Invalid Person ID​

This error is returned when the provided person ID is malformed or does not follow the expected format (e.g., not a valid UUID).

{
  "code": "invalid_person_id",
  "message": "Person id is invalid",
  "data": {
    "status": 400
  }
}

📚 Related Documentation​