---
updatedAt: 2026-07-01T14:20:06.000Z
agentTools:
  projectIndex: https://kulipa.readme.io/llms.txt
---

# Set the phone number of a user

Set the phone number of the specified user identified by its ID.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "x-readme": {
    "explorer-enabled": false,
    "samples-languages": [
      "javascript",
      "node",
      "kotlin",
      "swift",
      "objectivec",
      "shell",
      "java",
      "php",
      "go",
      "ruby"
    ],
    "proxy-enabled": true
  },
  "info": {
    "description": "Users are the core entity of the Kulipa card system. A user is an individual that owns crypto funds which they wish to spend via a Kulipa card. A user can have multiple cards, but a card can only be associated with one user.\n\nIn order for users to start using the system, you as the wallet provider must create a user in the system, as well as associate a blockchain address for that user and perform KYC on the user using our API. This is done in one call using the `POST` `/kyc` endpoint.\nOnce the user is verified, you can create cards for the user.\n",
    "version": "1.0.0",
    "title": "About users"
  },
  "tags": [
    {
      "name": "User",
      "description": "The `users` endpoint signifies an individual utilizing funds managed by Kulipa\nthrough a Kulipa card, whether physical or virtual.\nThis endpoint lets you manage users within the Kulipa system.\n\nIt retains details related to the user like their name, residence, birth date, along with financial data like card balances.\n\n> 📘 Info\n> To create a user, you should use the `POST` `/kyc` call in the KYC endpoint to simultaneously create the user and initiate the KYC verification process.\n> This will also create and associate a wallet for the user.\n",
      "x-displayName": "Managing users"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "tags": [
          "User"
        ],
        "summary": "List users",
        "description": "Provides a collection of User entities.\nThese entities are ordered in decreasing order based on their creation date,\nwith the newest object listed at the beginning.\n",
        "operationId": "listUsers",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "A limit on the number of objects returned from the call.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int16",
              "default": 10,
              "minimum": 1,
              "maximum": 100
            },
            "example": 10
          },
          {
            "name": "fromPage",
            "in": "query",
            "description": "Designates the start page in the sort order from which data should be retrieved",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int16",
              "minimum": 0,
              "default": 0
            },
            "example": 0
          },
          {
            "name": "sortBy",
            "in": "query",
            "description": "Designates the field to sort on.\nThere is a limited set of fields to sort on.\nPreface the field name with a hyphen (`-`) to sort in a descending order.\nExclude the hyphen to sort in ascending order.\n",
            "required": false,
            "schema": {
              "type": "string",
              "default": "-createdAt"
            },
            "example": "updatedAt"
          },
          {
            "name": "companyId",
            "in": "query",
            "description": "The UUID of the user's company",
            "schema": {
              "description": "A Company identifier. Begins with 'cmp-' followed by a [v4 UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))",
              "type": "string",
              "minLength": 40,
              "maxLength": 40,
              "pattern": "^cmp-[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$",
              "example": "cmp-f1112747-20c3-499f-8e05-a1a7aa0a1729"
            }
          },
          {
            "name": "email",
            "in": "query",
            "description": "The email of the user",
            "schema": {
              "$ref": "#/components/schemas/CommonUserBody/properties/email"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of users",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer",
                          "description": "The index of the page from the result",
                          "format": "int16",
                          "example": 1
                        },
                        "count": {
                          "type": "integer",
                          "description": "The number of items returned.",
                          "format": "int16",
                          "example": 10
                        },
                        "hasMore": {
                          "type": "boolean",
                          "description": "Indicates if more elements exist beyond this set. If it's false, this set represents the end of the list.",
                          "example": true
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "description": "A collection of users\n",
                          "items": {
                            "$ref": "#/components/schemas/User"
                          }
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "ListTwoUsers": {
                    "$ref": "#/components/examples/ListTwoUsers"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing)."
          },
          "401": {
            "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response."
          },
          "403": {
            "description": "The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike `401` Unauthorized, the client's identity is known to the server."
          },
          "429": {
            "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")."
          },
          "500": {
            "description": "The server has encountered a situation it does not know how to handle."
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/users/{id}/phone-number": {
      "put": {
        "tags": [
          "User"
        ],
        "summary": "Set the phone number of a user",
        "description": "Set the phone number of the specified user identified by its ID.\n",
        "operationId": "setUserPhoneNumber",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The UUID of the user",
            "required": true,
            "schema": {
              "$ref": "#/paths/~1users~1%7Bid%7D/get/parameters/0/schema"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CommonUserBody/properties/phone"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User with updated phone number",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                },
                "examples": {
                  "Johnny": {
                    "$ref": "#/components/examples/Johnny"
                  },
                  "Santa": {
                    "$ref": "#/components/examples/Santa"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/paths/~1users/get/responses/400"
          },
          "401": {
            "$ref": "#/paths/~1users/get/responses/401"
          },
          "403": {
            "$ref": "#/paths/~1users/get/responses/403"
          },
          "429": {
            "$ref": "#/paths/~1users/get/responses/429"
          },
          "500": {
            "$ref": "#/paths/~1users/get/responses/500"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "LegalName": {
        "description": "The user's legal name as per KYC provider.",
        "type": "object",
        "required": [
          "firstName",
          "lastName"
        ],
        "properties": {
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          }
        }
      },
      "ConsumerUser": {
        "title": "Consumer user",
        "description": "A consumer user.",
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "allOf": [
                  {
                    "description": "Unique identifier for the user."
                  },
                  {
                    "$ref": "#/paths/~1users~1%7Bid%7D/get/parameters/0/schema"
                  }
                ]
              },
              "status": {
                "type": "string",
                "example": "active",
                "description": "The different statuses for a user:\n  * `unverified` - Upon creation, a user begins with this status, until kyc has been performed successfully.\n  * `active` - After a successfull kyc verification, the user get this status, enabling regular transaction activities.\n  * `frozen` - While Deposit are accepted, debit operations are blocked.\n  * `disabled` - The account disallows any transactions.\n  * `deleted` - The account has been terminated and reactivation is not possible.\n  * `revoked` - The account has been permanently revoked and reactivation is not possible.\n",
                "enum": [
                  "active",
                  "unverified",
                  "frozen",
                  "disabled",
                  "deleted",
                  "revoked"
                ]
              },
              "firstName": {
                "type": "string",
                "example": "Johnny",
                "description": "The first name of the user."
              },
              "lastName": {
                "type": "string",
                "example": "Doe",
                "description": "The last name of the user."
              },
              "email": {
                "$ref": "#/components/schemas/CommonUserBody/properties/email"
              },
              "phone": {
                "$ref": "#/components/schemas/CommonUserBody/properties/phone"
              },
              "dateOfBirth": {
                "type": "string",
                "example": "2000-12-31",
                "format": "date",
                "description": "Date of birth of the card user in `YYYY-MM-DD` format.\n"
              },
              "countryOfBirth": {
                "type": "string",
                "example": "FR",
                "description": "Place of birth of the card user in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.\n"
              },
              "countryOfResidence": {
                "type": "string",
                "example": "FR",
                "description": "Country of residence of the card user in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.\n"
              },
              "address": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/CommonUserBody/properties/address"
                  }
                ]
              },
              "shippingAddress": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/CommonUserBody/properties/shippingAddress"
                  }
                ]
              },
              "legalName": {
                "$ref": "#/components/schemas/LegalName"
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "createdAt": {
                "description": "Creation date",
                "type": "string",
                "format": "date-time",
                "example": "2023-08-07T08:46:01Z"
              },
              "updatedAt": {
                "description": "Last update date",
                "type": "string",
                "format": "date-time",
                "example": "2023-08-07T10:12:48Z"
              }
            }
          }
        ]
      },
      "BusinessUser": {
        "title": "Business user",
        "description": "A business user.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ConsumerUser"
          },
          {
            "type": "object",
            "properties": {
              "companyId": {
                "$ref": "#/paths/~1users/get/parameters/3/schema"
              }
            }
          }
        ]
      },
      "User": {
        "description": "A kulipa user.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/ConsumerUser"
          },
          {
            "$ref": "#/components/schemas/BusinessUser"
          }
        ]
      },
      "CommonUserBody": {
        "description": "Common User Data",
        "title": "Common User Payload",
        "type": "object",
        "required": [
          "countryOfResidence"
        ],
        "properties": {
          "firstName": {
            "type": "string",
            "example": "Johnny",
            "description": "The first name of the user - Minimum of 2 up to 64 characters in length as a string. In case the user have several `first names`, they can be concatenated with a whitespace.\n",
            "minLength": 2,
            "maxLength": 64
          },
          "lastName": {
            "type": "string",
            "example": "Doe",
            "description": "The last name of the user - Minimum of 2 up to 64 characters in length as a string. In case the user have several `last names`, they can be concatenated with a whitespace.\n",
            "minLength": 2,
            "maxLength": 64
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "user@kulipa.xyz",
            "description": "Legitimate email ID of the card user.\n",
            "maxLength": 303
          },
          "phone": {
            "description": "Phone number. This should be unique across all users.",
            "type": "object",
            "required": [
              "country",
              "number"
            ],
            "properties": {
              "country": {
                "type": "string",
                "example": "+33",
                "description": "Phone country prefix (for instance, +33). It should begin with a '+'."
              },
              "number": {
                "type": "string",
                "example": "731456598",
                "description": "Phone number, not including the country prefix, with a maximum of 12 digits."
              }
            }
          },
          "dateOfBirth": {
            "type": "string",
            "example": "2000-12-31",
            "format": "date",
            "description": "Date of birth of the card user in `YYYY-MM-DD` format.\n"
          },
          "countryOfBirth": {
            "type": "string",
            "example": "FR",
            "description": "Country of birth of the card user in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.\n",
            "maxLength": 2
          },
          "countryOfResidence": {
            "type": "string",
            "example": "FR",
            "description": "Country of residence of the card user in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.\n",
            "maxLength": 2
          },
          "address": {
            "title": "Address Data",
            "type": "object",
            "required": [
              "address1",
              "postalCode",
              "city",
              "country"
            ],
            "properties": {
              "address1": {
                "type": "string",
                "description": "Number and street of the address (e.g., street or company name).",
                "maxLength": 150,
                "example": "20 W 34th St."
              },
              "address2": {
                "type": "string",
                "description": "Address complementary informations (e.g., apartment, place, or building).",
                "maxLength": 50,
                "example": "Empire State Building"
              },
              "postalCode": {
                "type": "string",
                "description": "Postal code or ZIP of the address.",
                "maxLength": 16,
                "example": "10001"
              },
              "city": {
                "type": "string",
                "description": "City of the address.",
                "maxLength": 50,
                "example": "New York"
              },
              "country": {
                "type": "string",
                "description": "Country code of the address in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). See the full list [here](https://www.iso.org/obp/ui/#search)",
                "maxLength": 2,
                "example": "US"
              },
              "state": {
                "type": "string",
                "description": "State, county, province, or region.",
                "maxLength": 12,
                "example": "NY"
              }
            }
          },
          "shippingAddress": {
            "type": "object",
            "required": [
              "address"
            ],
            "properties": {
              "address": {
                "allOf": [
                  {
                    "description": "Recipient address"
                  },
                  {
                    "$ref": "#/components/schemas/ConsumerUser/allOf/0/properties/address"
                  }
                ]
              },
              "phone": {
                "type": "string",
                "description": "Phone number of the recipient. One string of digits only with optional + at the start.",
                "maxLength": 20,
                "example": 12127363100
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "description": "Use the header: `x-api-key` to run authenticated calls to Kulipa API.\n",
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
      }
    },
    "examples": {
      "Johnny": {
        "summary": "Johnny user object",
        "value": {
          "id": "usr-825c1305-b268-4d3a-a64a-b4f6c315e50f",
          "status": "active",
          "firstName": "Johnny",
          "lastName": "Doe",
          "email": "johnny.doe@kulipa.xyz",
          "phone": {
            "country": 33,
            "number": 731456598
          },
          "dateOfBirth": "2000-12-31",
          "countryOfBirth": "FR",
          "countryOfResidence": "US"
        }
      },
      "Santa": {
        "summary": "Santa user object",
        "value": {
          "id": "usr-f852a802-52b5-4ed9-972e-f68c19111fb6",
          "status": "frozen",
          "firstName": "Santa",
          "lastName": "Barbara",
          "dateOfBirth": "1980-01-30",
          "countryOfBirth": "UK",
          "countryOfResidence": "UK"
        }
      }
    }
  }
}
```