> ## Documentation Index > Fetch the complete documentation index at: https://cantonfoundation-generated-references-ledger-bindings-update.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # POST /v2/parties > Allocates a new party on a ledger and adds it to the set managed by the participant. Caller specifies a party identifier suggestion, the actual identifier allocated might be different and is implementation specific. Caller can specify party metadata that is stored locally on the participant. This call may: - Succeed, in which case the actual allocated identifier is visible in the response. - Respond with a gRPC error daml-on-kv-ledger: suggestion's uniqueness is checked by the validators in the consensus layer and call rejected if the identifier is already present. canton: completely different globally unique identifier is allocated. Behind the scenes calls to an internal protocol are made. As that protocol is richer than the surface protocol, the arguments take implicit values The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space, colon, minus and underscore limited to 255 chars ## OpenAPI ````yaml /openapi/json-ledger-api/openapi.yaml post /v2/parties openapi: 3.0.3 info: title: JSON Ledger API HTTP endpoints version: 3.5.6 description: >- This specification version fixes the API inconsistencies where certain fields marked as required in the spec are in fact optional. If you use code generation tool based on this file, you might need to adjust the existing application code to handle those fields as optional. If you do not want to change your client code, continue using the OpenAPI specification for the latest Canton 3.4 patch release. MINIMUM_CANTON_VERSION=3.5.6 servers: [] security: [] paths: /v2/parties: post: summary: POST /v2/parties description: >- Allocates a new party on a ledger and adds it to the set managed by the participant. Caller specifies a party identifier suggestion, the actual identifier allocated might be different and is implementation specific. Caller can specify party metadata that is stored locally on the participant. This call may: - Succeed, in which case the actual allocated identifier is visible in the response. - Respond with a gRPC error daml-on-kv-ledger: suggestion's uniqueness is checked by the validators in the consensus layer and call rejected if the identifier is already present. canton: completely different globally unique identifier is allocated. Behind the scenes calls to an internal protocol are made. As that protocol is richer than the surface protocol, the arguments take implicit values The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space, colon, minus and underscore limited to 255 chars operationId: postV2Parties requestBody: content: application/json: schema: $ref: '#/components/schemas/AllocatePartyRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/AllocatePartyResponse' '400': description: 'Invalid value, Invalid value for: body' content: text/plain: schema: type: string default: description: '' content: application/json: schema: $ref: '#/components/schemas/JsCantonError' security: - httpAuth: [] - apiKeyAuth: [] components: schemas: AllocatePartyRequest: title: AllocatePartyRequest description: |- Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id) OR IsAuthenticatedUser(user_id)`` type: object properties: partyIdHint: description: |- A hint to the participant which party ID to allocate. It can be ignored. Must be a valid PartyIdString (as described in ``value.proto``). Optional type: string localMetadata: $ref: '#/components/schemas/ObjectMeta' description: >- Formerly "display_name" Participant-local metadata to be stored in the ``PartyDetails`` of this newly allocated party. Optional identityProviderId: description: >- The id of the ``Identity Provider`` If not set, assume the party is managed by the default identity provider or party is not hosted by the participant. Optional type: string synchronizerId: description: >- The synchronizer, on which the party should be allocated. For backwards compatibility, this field may be omitted, if the participant is connected to only one synchronizer. Otherwise a synchronizer must be specified. Optional type: string userId: description: >- The user who will get the act_as rights to the newly allocated party. If set to an empty string (the default), no user will get rights to the party. Optional type: string AllocatePartyResponse: title: AllocatePartyResponse type: object required: - partyDetails properties: partyDetails: $ref: '#/components/schemas/PartyDetails' description: |- The allocated party details Required JsCantonError: title: JsCantonError type: object required: - code - cause - context - errorCategory properties: code: type: string cause: type: string correlationId: type: string traceId: type: string context: $ref: '#/components/schemas/Map_String' resources: type: array items: $ref: '#/components/schemas/Tuple2_String_String' errorCategory: type: integer format: int32 grpcCodeValue: type: integer format: int32 retryInfo: type: string definiteAnswer: type: boolean ObjectMeta: title: ObjectMeta description: >- Represents metadata corresponding to a participant resource (e.g. a participant user or participant local information about a party). Based on ``ObjectMeta`` meta used in Kubernetes API. See https://github.com/kubernetes/apimachinery/blob/master/pkg/apis/meta/v1/generated.proto#L640 type: object properties: resourceVersion: description: >- An opaque, non-empty value, populated by a participant server which represents the internal version of the resource this ``ObjectMeta`` message is attached to. The participant server will change it to a unique value each time the corresponding resource is updated. You must not rely on the format of resource version. The participant server might change it without notice. You can obtain the newest resource version value by issuing a read request. You may use it for concurrent change detection by passing it back unmodified in an update request. The participant server will then compare the passed value with the value maintained by the system to determine if any other updates took place since you had read the resource version. Upon a successful update you are guaranteed that no other update took place during your read-modify-write sequence. However, if another update took place during your read-modify-write sequence then your update will fail with an appropriate error. Concurrent change control is optional. It will be applied only if you include a resource version in an update request. When creating a new instance of a resource you must leave the resource version empty. Its value will be populated by the participant server upon successful resource creation. Optional type: string annotations: $ref: '#/components/schemas/Map_String' description: >- A set of modifiable key-value pairs that can be used to represent arbitrary, client-specific metadata. Constraints: 1. The total size over all keys and values cannot exceed 256kb in UTF-8 encoding. 2. Keys are composed of an optional prefix segment and a required name segment such that: - key prefix, when present, must be a valid DNS subdomain with at most 253 characters, followed by a '/' (forward slash) character, - name segment must have at most 63 characters that are either alphanumeric ([a-z0-9A-Z]), or a '.' (dot), '-' (dash) or '_' (underscore); and it must start and end with an alphanumeric character. 3. Values can be any non-empty strings. Keys with empty prefix are reserved for end-users. Properties set by external tools or internally by the participant server must use non-empty key prefixes. Duplicate keys are disallowed by the semantics of the protobuf3 maps. See: https://developers.google.com/protocol-buffers/docs/proto3#maps Annotations may be a part of a modifiable resource. Use the resource's update RPC to update its annotations. In order to add a new annotation or update an existing one using an update RPC, provide the desired annotation in the update request. In order to remove an annotation using an update RPC, provide the target annotation's key but set its value to the empty string in the update request. Modifiable Optional: can be empty PartyDetails: title: PartyDetails type: object required: - party properties: party: description: |- The stable unique identifier of a Daml party. Must be a valid PartyIdString (as described in ``value.proto``). Required type: string isLocal: description: >- true if party is hosted by the participant and the party shares the same identity provider as the user issuing the request. Optional type: boolean localMetadata: $ref: '#/components/schemas/ObjectMeta' description: |- Participant-local metadata of this party. Modifiable Optional identityProviderId: description: >- The id of the ``Identity Provider`` Optional, if not set, there could be 3 options: 1. the party is managed by the default identity provider. 2. party is not hosted by the participant. 3. party is hosted by the participant, but is outside of the user's identity provider. Optional type: string Map_String: title: Map_String type: object additionalProperties: type: string Tuple2_String_String: title: Tuple2_String_String type: array maxItems: 2 minItems: 2 items: type: string securitySchemes: httpAuth: type: http description: Ledger API standard JWT token scheme: bearer apiKeyAuth: type: apiKey description: Ledger API standard JWT token (websocket) name: Sec-WebSocket-Protocol in: header ````