UpdateClient

UpdateClient updates a single client's compliance profile.

Update access is restricted based on the client's current verification status:

When status is VERIFICATION_STATUS_NOT_STARTED or VERIFICATION_STATUS_FAILED:

• Full update access to all mutable fields.
• The following fields are never updatable: name, owner, owners, verification_status, verification_date, next_verification_date.

When status is VERIFICATION_STATUS_PENDING or VERIFICATION_STATUS_VERIFIED:

• Only the verification authority may update the client.
• The following fields remain non-updatable: name, owner, owners.

Overview

Method Options

Authorisation specification of the UpdateClient method.

Type	METHOD_TYPE_WRITE
Access Level	METHOD_ACCESS_LEVEL_AUTHORISED
Roles	ROLE_COMPLIANCE_ADMIN ROLE_COMPLIANCE_CLIENT_ADMIN

Parameters

Request and response parameter message overview:

Input: UpdateClientRequest Message

Field	Type	Required	Description
Client	meshtrade.compliance.client.v1.Client	True	The client resource with updated values. The name field must be set to identify which client to update. Only provided fields will be modified, subject to the state-based access restrictions documented on UpdateClient.

Returns: Client Message

Protobuf

syntax = "proto3";

package meshtrade.compliance.client.v1;

import "buf/validate/validate.proto";
import "google/protobuf/timestamp.proto";
import "meshtrade/compliance/client/v1/client.proto";
import "meshtrade/option/method_options/v1/method_options.proto";

option go_package = "github.com/meshtrade/api/go/compliance/client/v1;client_v1";
option java_package = "co.meshtrade.api.compliance.client.v1";

// Service manages client profiles for compliance and Know Your Customer (KYC)
// purposes.
//
// The main entity managed by this service is the `Client` resource. A client can
// be a natural person, company, or trust. This service allows you to retrieve
// the compliance profiles for these clients.
service ClientService {
  // CreateClient creates a single client.
  rpc CreateClient(CreateClientRequest) returns (meshtrade.compliance.client.v1.Client) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_COMPLIANCE_ADMIN,
        ROLE_COMPLIANCE_CLIENT_ADMIN
      ]
    };
  }

  // GetClient retrieves a single client's compliance profile by its unique resource name.
  //
  // This allows for fetching the complete compliance details of a specific client,
  // including all associated information like identification documents, tax residencies,
  // and company structures.
  rpc GetClient(GetClientRequest) returns (meshtrade.compliance.client.v1.Client) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_COMPLIANCE_ADMIN,
        ROLE_COMPLIANCE_VIEWER,
        ROLE_COMPLIANCE_CLIENT_ADMIN,
        ROLE_COMPLIANCE_CLIENT_VIEWER
      ]
    };
  }

  // GetGroupClient retrieves the client compliance profile associated with a specific group.
  //
  // This allows fetching the compliance details of the client that is owned by
  // the specified group, using the group's resource name as the lookup key.
  rpc GetGroupClient(GetGroupClientRequest) returns (meshtrade.compliance.client.v1.Client) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_COMPLIANCE_ADMIN,
        ROLE_COMPLIANCE_VIEWER,
        ROLE_COMPLIANCE_CLIENT_ADMIN,
        ROLE_COMPLIANCE_CLIENT_VIEWER
      ]
    };
  }

  // UpdateClient updates a single client's compliance profile.
  //
  // Update access is restricted based on the client's current verification status:
  //
  // When status is VERIFICATION_STATUS_NOT_STARTED or VERIFICATION_STATUS_FAILED:
  //   - Full update access to all mutable fields.
  //   - The following fields are never updatable: name, owner, owners,
  //     verification_status, verification_date, next_verification_date.
  //
  // When status is VERIFICATION_STATUS_PENDING or VERIFICATION_STATUS_VERIFIED:
  //   - Only the verification authority may update the client.
  //   - The following fields remain non-updatable: name, owner, owners.
  rpc UpdateClient(UpdateClientRequest) returns (meshtrade.compliance.client.v1.Client) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_COMPLIANCE_ADMIN,
        ROLE_COMPLIANCE_CLIENT_ADMIN
      ]
    };
  }

  // StartClientVerification transitions a client to VERIFICATION_STATUS_PENDING.
  //
  // Valid only when the client's current status is VERIFICATION_STATUS_NOT_STARTED
  // or VERIFICATION_STATUS_FAILED. Callable by either the verification authority
  // or the client's owning group.
  rpc StartClientVerification(StartClientVerificationRequest) returns (meshtrade.compliance.client.v1.Client) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_COMPLIANCE_ADMIN,
        ROLE_COMPLIANCE_CLIENT_ADMIN
      ]
    };
  }

  // FailClientVerification transitions a client to VERIFICATION_STATUS_FAILED.
  //
  // Valid only when the client's current status is VERIFICATION_STATUS_PENDING.
  // Only callable by the verification authority. Requires comments explaining
  // the reason for failure.
  rpc FailClientVerification(FailClientVerificationRequest) returns (meshtrade.compliance.client.v1.Client) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_COMPLIANCE_ADMIN,
        ROLE_COMPLIANCE_CLIENT_ADMIN
      ]
    };
  }

  // MarkClientVerified transitions a client to VERIFICATION_STATUS_VERIFIED.
  //
  // Valid only when the client's current status is VERIFICATION_STATUS_PENDING.
  // Only callable by the verification authority. Sets verification_date to now
  // and next_verification_date to the provided value.
  // The next_verification_date must be after the existing verification_date and
  // next_verification_date (if set).
  rpc MarkClientVerified(MarkClientVerifiedRequest) returns (meshtrade.compliance.client.v1.Client) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_COMPLIANCE_ADMIN,
        ROLE_COMPLIANCE_CLIENT_ADMIN
      ]
    };
  }

  // ListClients retrieves a collection of client compliance profiles.
  //
  // This method is useful for fetching multiple client records at once.
  // Note: This endpoint does not currently support pagination or filtering.
  rpc ListClients(ListClientsRequest) returns (ListClientsResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_COMPLIANCE_ADMIN,
        ROLE_COMPLIANCE_VIEWER,
        ROLE_COMPLIANCE_CLIENT_ADMIN,
        ROLE_COMPLIANCE_CLIENT_VIEWER
      ]
    };
  }
}

// GetClientRequest is the message used to request a single client resource.
message GetClientRequest {
  // The unique resource name of the client to be retrieved.
  // The name serves as the primary identifier for the client resource.
  // Format: "compliance/clients/{client_id}"
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 45
      pattern: "^compliance/clients/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
}

// CreateClientRequest is the message used to create a single client resource.
message CreateClientRequest {
  // Client is the client resource to create.
  meshtrade.compliance.client.v1.Client client = 1 [(buf.validate.field) = {required: true}];
}

// UpdateClientRequest is the message used to update a single client resource.
message UpdateClientRequest {
  // The client resource with updated values.
  // The name field must be set to identify which client to update.
  // Only provided fields will be modified, subject to the state-based
  // access restrictions documented on UpdateClient.
  meshtrade.compliance.client.v1.Client client = 1 [(buf.validate.field) = {required: true}];
}

// GetGroupClientRequest is the message used to request a client resource by its owning group.
message GetGroupClientRequest {
  // The resource name of the group whose client is to be retrieved.
  // Format: "groups/{group_id}"
  string group = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 33
      pattern: "^groups/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
}

// StartClientVerificationRequest is the message used to start verification for a client.
message StartClientVerificationRequest {
  // The resource name of the client to start verification for.
  // Format: "compliance/clients/{client_id}"
  string client = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 45
      pattern: "^compliance/clients/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
}

// FailClientVerificationRequest is the message used to fail verification for a client.
message FailClientVerificationRequest {
  // The resource name of the client whose verification has failed.
  // Format: "compliance/clients/{client_id}"
  string client = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 45
      pattern: "^compliance/clients/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  // Comments explaining the reason for verification failure.
  // At least one comment is required.
  repeated string comments = 2 [(buf.validate.field) = {
    required: true
    repeated: {
      min_items: 1
      items: {
        string: {
          min_len: 1
          max_len: 1000
        }
      }
    }
  }];
}

// MarkClientVerifiedRequest is the message used to mark a client as verified.
message MarkClientVerifiedRequest {
  // The resource name of the client to mark as verified.
  // Format: "compliance/clients/{client_id}"
  string client = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 45
      pattern: "^compliance/clients/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  // The date when the next periodic compliance review is due.
  // Optional. If not provided, defaults to a system-configured value.
  // When provided, must be in the future and after the client's existing
  // verification_date and next_verification_date (if those fields are set).
  google.protobuf.Timestamp next_verification_date = 2 [(buf.validate.field) = {
    timestamp: {gt_now: true}
  }];
}

// ListClientsRequest is the message used to request a list of client resources.
message ListClientsRequest {}

// ListClientsResponse contains a list of client resources.
message ListClientsResponse {
  // A repeated field containing the client resource objects.
  repeated meshtrade.compliance.client.v1.Client clients = 1;
}

Code Examples

Select supported SDK in the language of your choice for a full example of how to invoke the this method:

Go

package main

import (
	"context"
	"log"

	clientv1 "github.com/meshtrade/api/go/compliance/client/v1"
)

func main() {
	ctx := context.Background()

	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
	// environment variable or default discovery methods. Zero config required
	// unless you want custom configuration.
	service, err := clientv1.NewClientService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Update the client's display name
	request := &clientv1.UpdateClientRequest{
		Client: &clientv1.Client{
			Name:        "compliance/clients/01HQZXYZ9ABCDEFGHIJKLMNPQR",
			DisplayName: "Updated Client Name",
			ShortName:   "UCN",
		},
	}

	// Call the UpdateClient method
	client, err := service.UpdateClient(ctx, request)
	if err != nil {
		log.Fatalf("UpdateClient failed: %v", err)
	}

	log.Printf("Client updated: %s", client.DisplayName)
}

Python

from meshtrade.compliance.client.v1 import (
    Client,
    ClientService,
    UpdateClientRequest,
)


def main():
    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
    # environment variable or default discovery methods. Zero config required
    # unless you want custom configuration.
    service = ClientService()

    with service:
        # Update the client's display name
        request = UpdateClientRequest(
            client=Client(
                name="compliance/clients/01HQZXYZ9ABCDEFGHIJKLMNPQR",
                display_name="Updated Client Name",
                short_name="UCN",
            )
        )

        # Call the UpdateClient method
        client = service.update_client(request)

        print(f"Client updated: {client.display_name}")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.compliance.client.v1.ClientService;
import co.meshtrade.api.compliance.client.v1.Service.UpdateClientRequest;
import co.meshtrade.api.compliance.client.v1.Client.Client;

import java.util.Optional;

public class UpdateClientExample {
    public static void main(String[] args) {
        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
        // environment variable or default discovery methods. Zero config required
        // unless you want custom configuration.
        try (ClientService service = new ClientService()) {
            // Update the client's display name
            UpdateClientRequest request = UpdateClientRequest.newBuilder()
                .setClient(Client.newBuilder()
                    .setName("compliance/clients/01HQZXYZ9ABCDEFGHIJKLMNPQR")
                    .setDisplayName("Updated Client Name")
                    .setShortName("UCN")
                    .build())
                .build();

            // Call the UpdateClient method
            Client client = service.updateClient(request, Optional.empty());

            System.out.println("Client updated: " + client.getDisplayName());
        } catch (Exception e) {
            System.err.println("UpdateClient failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Advanced Configuration

For advanced client configuration options (custom endpoints, TLS settings, timeouts), see the SDK Configuration Guide.

Other Methods

• Compliance Client v1 Method List - For Other methods