Usage Examples¶
This page contains practical, real-world code examples for common tasks using the CX Platform Java SDK. Each example is self-contained — copy it into your project and adapt as needed.
Prerequisites
All examples assume you have completed the Quick Start and
have a configured CxSdkClient instance. They also assume the service
location has already been set for the same location key before running
downstream calls such as customer, statement, and payment operations:
import com.gp.cx.sdk.client.CxSdkClient;
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
Error Handling
All production code should wrap API calls in try/catch to handle
CxSdkClientException. Every example on this page includes a try/catch
block. See Error Handling for full patterns, retry
strategies, and the ErrorCategory enum.
Managing API Keys¶
Generate a Location API key using an Implementation-level key. The returned key is used to create a location-scoped client for all downstream operations.
REST API endpoint
POST /cx/v2/apikey — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.ApiKeyApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ApiKeyResponseDTO;
public class ApiKeyExample {
public static void main(String[] args) {
// Use an Implementation-level key to generate a Location key
CxSdkClient implClient = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_IMPLEMENTATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
ApiKeyApi apiKeyApi = implClient.getApiKeyApi();
try {
ApiKeyResponseDTO keyResponse = apiKeyApi.createApiKeyForNewLocation();
String locationApiKey = keyResponse.getApiKey();
System.out.println("Location API key generated.");
// Build a location-scoped client with the new key
CxSdkClient locationClient = new CxSdkClient.Builder()
.apiKey(locationApiKey)
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
System.out.println("Location-scoped client ready.");
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Location API key generated.
Location-scoped client ready.
Working with Service Locations¶
Start by creating or updating the service location tied to the Location API key. Run this before downstream calls such as customer, statement, and payment request operations.
REST API endpoint
POST /cx/v2/action/setServiceLocation — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.ServiceLocationApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ChannelAddressDTO;
import com.gp.cx.sdk.model.ChannelEmailDTO;
import com.gp.cx.sdk.model.ChannelPhoneDTO;
import com.gp.cx.sdk.model.ServiceLocationDTO;
public class ServiceLocationExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
ServiceLocationApi serviceLocationApi = client.getServiceLocationApi();
ServiceLocationDTO serviceLocationRequest = new ServiceLocationDTO()
.name("Downtown Office")
.locale("en-US")
.timeZone("America/Denver")
.primaryPhone(new ChannelPhoneDTO().value("+18015555555"))
.primaryEmail(new ChannelEmailDTO().value("office@example.com"))
.primaryAddress(new ChannelAddressDTO()
.postalCode("84101")
.streetAddress1("456 Oak Avenue")
.streetAddress2("Suite 200")
.streetAddress3("Salt Lake City, Utah")
.country(ChannelAddressDTO.CountryEnum.US));
try {
ServiceLocationDTO serviceLocationCreated =
serviceLocationApi.setServiceLocation(serviceLocationRequest);
System.out.println("Service location created: " + serviceLocationCreated.getName());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Service location created: Downtown Office
Creating a Customer¶
Create a customer with full contact and demographic details:
REST API endpoint
POST /cx/v2/action/setCustomer — See the Swagger UI for the full request/response schema.
import java.time.LocalDate;
import com.gp.cx.sdk.api.CustomersApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ChannelAddressDTO;
import com.gp.cx.sdk.model.ChannelEmailDTO;
import com.gp.cx.sdk.model.ChannelPhoneDTO;
import com.gp.cx.sdk.model.CustomerDTO;
public class CreateCustomerExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
CustomersApi customersApi = client.getCustomersApi();
CustomerDTO customerRequest = new CustomerDTO()
.givenName("Ol")
.familyName("Persson")
.dateOfBirth(LocalDate.of(1990, 6, 15))
.sex("FEMALE")
.locale("en-US")
.primaryPhone(new ChannelPhoneDTO().value("+18015555555"))
.primaryEmail(new ChannelEmailDTO().value("cx-test@tsys.com"))
.primaryAddress(new ChannelAddressDTO()
.country(ChannelAddressDTO.CountryEnum.US)
.streetAddress1("123 Main Street")
.postalCode("84045"));
try {
CustomerDTO customerCreated = customersApi.setCustomer(customerRequest);
System.out.println("Created customer: " + customerCreated.getDisplayCustomerId());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Created customer: Customer-12345
Retrieving a Customer by ID¶
REST API endpoint
GET /cx/v2/customer/{id} — See the Swagger UI for the full request/response schema.
import java.time.LocalDate;
import com.gp.cx.sdk.api.CustomersApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ChannelAddressDTO;
import com.gp.cx.sdk.model.ChannelEmailDTO;
import com.gp.cx.sdk.model.ChannelPhoneDTO;
import com.gp.cx.sdk.model.CustomerDTO;
public class GetCustomerExample {
public static void main(String[] args) {
CustomersApi customersApi = client.getCustomersApi();
try {
CustomerDTO request = new CustomerDTO()
.givenName("Ol")
.familyName("Persson")
.displayCustomerId("Customer-12345")
.dateOfBirth(LocalDate.of(2024, 10, 8))
.sex("MALE")
.locale("en-US")
.primaryPhone(new ChannelPhoneDTO().value("+18015555555"))
.primaryEmail(new ChannelEmailDTO().value("cx-test@tsys.com"))
.primaryAddress(new ChannelAddressDTO()
.country(ChannelAddressDTO.CountryEnum.US)
.streetAddress1("123 Easy Street")
.streetAddress2("Suite 101")
.streetAddress3("Testington, Alabama")
.postalCode("55555")
.poBox("PO Box 12345"));
CustomerDTO created = customersApi.setCustomer(request);
CustomerDTO customer = customersApi.getCustomerById(created.getId());
System.out.println("Customer ID: " + customer.getId());
System.out.println("Name: " + customer.getGivenName() + " " + customer.getFamilyName());
System.out.println("Display ID: " + customer.getDisplayCustomerId());
System.out.println("DOB: " + customer.getDateOfBirth());
System.out.println("Phone: " + customer.getPrimaryPhone().getValue());
System.out.println("Email: " + customer.getPrimaryEmail().getValue());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Customer ID: 6fd9d54d-3d2e-4f4d-9b0a-2efc3d95ad3a
Name: Ol Persson
Display ID: Customer-12345
DOB: 2024-10-08
Phone: +18015555555
Email: cx-test@tsys.com
Creating an Event Template¶
Create a new event template, confirm it appears in list results, then fetch it by ID:
REST API endpoint
POST /cx/scheduling/eventTemplate — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.EventsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.EmbeddedServiceLocation;
import com.gp.cx.sdk.model.EventTemplateDTO;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.MetadataBodyDto;
import com.gp.cx.sdk.model.RequirementsDTO;
import com.gp.cx.sdk.model.ScenarioDTO;
import java.util.Arrays;
import java.util.HashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
public class CreateEventTemplateExample {
public static void main(String[] args) {
EventsApi eventsApi = client.getEventsApi();
String serviceLocationId = "service-location-uuid-here";
try {
EventTemplateDTO request = buildEventTemplate(serviceLocationId);
EventTemplateDTO created = eventsApi.createEventTemplate(request);
List<EventTemplateDTO> allTemplates = eventsApi.getAllEventTemplates();
boolean foundInList = allTemplates.stream()
.anyMatch(t -> request.getName().equals(t.getName()));
EventTemplateDTO fetched = eventsApi.getTemplate(created.getId());
System.out.println("Created template ID: " + created.getId());
System.out.println("Created template name: " + created.getName());
System.out.println("Found in template list: " + foundInList);
System.out.println("Fetched template name: " + fetched.getName());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
private static EventTemplateDTO buildEventTemplate(String serviceLocationId) {
EventTemplateDTO eventTemplateDTO = new EventTemplateDTO();
eventTemplateDTO.setName("Haircut Appointment");
eventTemplateDTO.setDescription("A haircut by one of our professional stylists.");
eventTemplateDTO.setActive(true);
eventTemplateDTO.setColor("string");
ScenarioDTO scenario = new ScenarioDTO();
RequirementsDTO requirement = new RequirementsDTO();
requirement.setTags(new LinkedHashSet<>(Arrays.asList("instructor", "cx-staff")));
scenario.setRequirements(Arrays.asList(requirement));
scenario.setDuration("PT30M");
scenario.setPrice(0);
eventTemplateDTO.setScenarios(Arrays.asList(scenario));
MetadataBodyDto metadata = new MetadataBodyDto();
metadata.setExternalId("ID-12345");
Map<String, String> data = new HashMap<>();
data.put("additionalProp1", "string");
data.put("additionalProp2", "string");
data.put("additionalProp3", "string");
metadata.setData(data);
eventTemplateDTO.setMyMetadata(metadata);
EmbeddedServiceLocation embedded = new EmbeddedServiceLocation();
IDWrapper serviceLocation = new IDWrapper();
serviceLocation.setId(serviceLocationId);
MetadataBodyDto serviceLocationMetadata = new MetadataBodyDto();
serviceLocationMetadata.setExternalId("ID-12345");
Map<String, String> serviceLocationData = new HashMap<>();
serviceLocationData.put("additionalProp1", "string");
serviceLocationData.put("additionalProp2", "string");
serviceLocationData.put("additionalProp3", "string");
serviceLocationMetadata.setData(serviceLocationData);
serviceLocation.setMyMetadata(serviceLocationMetadata);
embedded.setServiceLocation(serviceLocation);
eventTemplateDTO.setEmbedded(embedded);
return eventTemplateDTO;
}
}
Expected output:
Created template ID: tmpl-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Created template name: Haircut Appointment
Found in template list: true
Fetched template name: Haircut Appointment
Retrieving All Event Templates¶
Fetch all event templates configured for the service location:
REST API endpoint
GET /cx/scheduling/eventTemplate — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.EventsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.EventTemplateDTO;
import java.util.List;
public class GetAllEventTemplatesExample {
public static void main(String[] args) {
EventsApi eventsApi = client.getEventsApi();
try {
List<EventTemplateDTO> templates = eventsApi.getAllEventTemplates();
System.out.println("Event templates found: " + templates.size());
if (!templates.isEmpty()) {
EventTemplateDTO first = templates.get(0);
System.out.println("First template ID: " + first.getId());
System.out.println("First template name: " + first.getName());
}
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Event templates found: 3
First template ID: tmpl-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
First template name: Initial Consultation
Updating an Event Template¶
Update an existing template name and scenario data, then verify the change:
REST API endpoint
PUT /cx/scheduling/eventTemplate/{id} — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.EventsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.EventTemplateDTO;
import com.gp.cx.sdk.model.ScenarioDTO;
import java.util.ArrayList;
import java.util.List;
public class UpdateEventTemplateExample {
public static void main(String[] args) {
EventsApi eventsApi = client.getEventsApi();
try {
List<EventTemplateDTO> templates = eventsApi.getAllEventTemplates();
if (templates.isEmpty()) {
System.out.println("No event templates available.");
return;
}
EventTemplateDTO original = templates.get(0);
String templateId = original.getId();
String originalName = original.getName();
String updatedName = originalName + "_updated_" + System.currentTimeMillis();
List<ScenarioDTO> scenarios = original.getScenarios();
if (scenarios == null || scenarios.isEmpty()) {
scenarios = new ArrayList<>();
ScenarioDTO scenario = new ScenarioDTO()
.duration("PT10M")
.price(11)
.requirements(new ArrayList<>());
scenarios.add(scenario);
} else {
scenarios.get(0).price(10);
}
EventTemplateDTO updateDto = new EventTemplateDTO()
.id(null)
.name(updatedName)
.description(original.getDescription())
.color(original.getColor())
.active(original.getActive())
.scenarios(scenarios);
EventTemplateDTO updated = eventsApi.updateTemplate(templateId, updateDto);
EventTemplateDTO fetched = eventsApi.getTemplate(updated.getId());
System.out.println("Template updated: " + updated.getId());
System.out.println("Updated name: " + fetched.getName());
updateDto.name(originalName);
eventsApi.updateTemplate(templateId, updateDto);
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Template updated: tmpl-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Updated name: Initial Consultation_updated_1720476485123
Getting Availability by Event Template¶
Query availability for a template using daysOnly=true (useful for month view):
REST API endpoint
GET /cx/scheduling/availability — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.EventsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.AvailabilityDTO;
import com.gp.cx.sdk.model.EventTemplateDTO;
import java.time.OffsetDateTime;
import java.util.List;
public class GetAvailabilityExample {
public static void main(String[] args) {
EventsApi eventsApi = client.getEventsApi();
try {
List<EventTemplateDTO> templates = eventsApi.getAllEventTemplates();
if (templates.isEmpty()) {
System.out.println("No event templates available.");
return;
}
String templateId = templates.get(0).getId();
OffsetDateTime start = OffsetDateTime.now();
OffsetDateTime end = start.plusDays(6);
AvailabilityDTO availability = eventsApi.getAvailability(start, end, templateId, null, true);
System.out.println("Template ID: " + templateId);
System.out.println("Availability response received: " + (availability != null));
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Template ID: tmpl-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Availability response received: true
Creating an Event¶
Schedule a service event for a customer:
REST API endpoint
POST /cx/v2/action/setEvent — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.EventsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.EmbeddedCustomer;
import com.gp.cx.sdk.model.EventDTO;
import com.gp.cx.sdk.model.IDWrapper;
import java.time.OffsetDateTime;
public class CreateEventExample {
public static void main(String[] args) {
EventsApi eventsApi = client.getEventsApi();
EmbeddedCustomer embedded = new EmbeddedCustomer()
.customer(new IDWrapper().id("customer-uuid-here"));
EventDTO eventRequest = new EventDTO()
.title("Annual Checkup")
.startDateTime(OffsetDateTime.parse("2026-08-15T10:00:00Z"))
.endDateTime(OffsetDateTime.parse("2026-08-15T11:00:00Z"))
.embedded(embedded);
try {
EventDTO createdEvent = eventsApi.setEvent(eventRequest);
System.out.println("Event created: " + createdEvent.getId());
System.out.println("Title: " + createdEvent.getTitle());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Event created: evt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Title: Annual Checkup
Retrieving Events for a Customer¶
Create a customer, add an event, then fetch events for that customer:
import com.gp.cx.sdk.api.CustomersApi;
import com.gp.cx.sdk.api.EventsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ChannelEmailDTO;
import com.gp.cx.sdk.model.ChannelPhoneDTO;
import com.gp.cx.sdk.model.CustomerDTO;
import com.gp.cx.sdk.model.EmbeddedEventContext;
import com.gp.cx.sdk.model.EventDTO;
import com.gp.cx.sdk.model.EventResponseDTO;
import com.gp.cx.sdk.model.IDWrapper;
import java.time.OffsetDateTime;
import java.util.HashMap;
import java.util.List;
public class GetCustomerEventsExample {
public static void main(String[] args) {
CustomersApi customersApi = client.getCustomersApi();
EventsApi eventsApi = client.getEventsApi();
try {
CustomerDTO customer = new CustomerDTO()
.givenName("Integration")
.familyName("Test")
.displayCustomerId("Integration-" + System.currentTimeMillis())
.primaryPhone(new ChannelPhoneDTO().value("+18015551234"))
.primaryEmail(new ChannelEmailDTO().value("integration-test@cx.com"));
CustomerDTO createdCustomer = customersApi.setCustomer(customer);
EventDTO event = new EventDTO()
.startDateTime(OffsetDateTime.now().plusDays(1))
.duration("PT30M")
.embedded(new EmbeddedEventContext()
.customer(new IDWrapper().id(createdCustomer.getId())));
EventResponseDTO createdEvent = eventsApi.setEvent(false, event, new HashMap<>());
List<EventDTO> events = customersApi.getEventsForCustomer(createdCustomer.getId());
boolean found = events.stream().anyMatch(e -> createdEvent.getId().equals(e.getId()));
System.out.println("Customer ID: " + createdCustomer.getId());
System.out.println("Events found: " + events.size());
System.out.println("Created event included: " + found);
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Customer ID: cst-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Events found: 1
Created event included: true
Canceling an Event¶
REST API endpoint
POST /cx/v2/action/cancelEvent — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.EventsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.CancelEventDTO;
public class CancelEventExample {
public static void main(String[] args) {
EventsApi eventsApi = client.getEventsApi();
try {
CancelEventDTO cancelRequest = new CancelEventDTO().id("event-uuid-here");
eventsApi.cancelEvent(cancelRequest);
System.out.println("Event canceled successfully.");
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Event canceled successfully.
Deleting an Event¶
Create an event, delete it, then confirm it is no longer retrievable:
REST API endpoint
DELETE /cx/scheduling/event/{eventId} — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.EventsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.EmbeddedEventContext;
import com.gp.cx.sdk.model.EventDTO;
import com.gp.cx.sdk.model.EventResponseDTO;
import com.gp.cx.sdk.model.IDWrapper;
import java.time.OffsetDateTime;
import java.util.HashMap;
public class DeleteEventExample {
public static void main(String[] args) {
EventsApi eventsApi = client.getEventsApi();
String serviceLocationId = "service-location-uuid-here";
try {
EventDTO event = new EventDTO()
.startDateTime(OffsetDateTime.now().plusDays(1))
.duration("PT30M")
.embedded(new EmbeddedEventContext()
.serviceLocation(new IDWrapper().id(serviceLocationId)));
EventResponseDTO created = eventsApi.setEvent(false, event, new HashMap<>());
String eventId = created.getId();
eventsApi.deleteEvent(eventId);
try {
eventsApi.getEvent(eventId);
System.out.println("Event still exists: " + eventId);
} catch (CxSdkClientException ex) {
boolean notFound = ex.getStatusCode() == 404
|| (ex.getMessage() != null && ex.getMessage().toLowerCase().contains("not found"));
System.out.println("Deleted event ID: " + eventId);
System.out.println("Event not found after delete: " + notFound);
System.err.println("API call failed:");
System.err.println(" Status code: " + ex.getStatusCode());
System.err.println(" Error category: " + ex.getErrorCategory());
System.err.println(" API error code: " + ex.getApiErrorCode());
System.err.println(" API message: " + ex.getApiErrorMessage());
System.err.println(" Retryable: " + ex.isRetryable());
System.err.println(" Response body: " + ex.getResponseBody());
}
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Deleted event ID: evt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Event not found after delete: true
Getting Events by Date Range¶
Create two events in a target window, then query events within that date range:
REST API endpoint
GET /cx/scheduling/event — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.EventsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.EmbeddedEventContext;
import com.gp.cx.sdk.model.EventDTO;
import com.gp.cx.sdk.model.EventResponseDTO;
import com.gp.cx.sdk.model.GetEventsResult;
import com.gp.cx.sdk.model.IDWrapper;
import java.time.OffsetDateTime;
import java.util.HashMap;
public class GetEventsByDateRangeExample {
public static void main(String[] args) {
EventsApi eventsApi = client.getEventsApi();
String serviceLocationId = "service-location-uuid-here";
try {
OffsetDateTime now = OffsetDateTime.now();
OffsetDateTime startDate = now.plusDays(10);
OffsetDateTime endDate = now.plusDays(20);
EventDTO event1 = new EventDTO()
.startDateTime(startDate.plusDays(2))
.duration("PT30M")
.description("Test event 1 within range")
.embedded(new EmbeddedEventContext()
.serviceLocation(new IDWrapper().id(serviceLocationId)));
EventDTO event2 = new EventDTO()
.startDateTime(startDate.plusDays(5))
.duration("PT45M")
.description("Test event 2 within range")
.embedded(new EmbeddedEventContext()
.serviceLocation(new IDWrapper().id(serviceLocationId)));
EventResponseDTO created1 = eventsApi.setEvent(false, event1, new HashMap<>());
EventResponseDTO created2 = eventsApi.setEvent(false, event2, new HashMap<>());
GetEventsResult result = eventsApi.getEventsByDateRange(startDate, endDate);
boolean hasEvent1 = result.getEvents().stream().anyMatch(e -> created1.getId().equals(e.getId()));
boolean hasEvent2 = result.getEvents().stream().anyMatch(e -> created2.getId().equals(e.getId()));
boolean allWithinRange = result.getEvents().stream().allMatch(e ->
e.getStartDateTime() != null
&& !e.getStartDateTime().isBefore(startDate)
&& !e.getStartDateTime().isAfter(endDate));
System.out.println("Events returned: " + result.getEvents().size());
System.out.println("Created event 1 included: " + hasEvent1);
System.out.println("Created event 2 included: " + hasEvent2);
System.out.println("All returned events in range: " + allWithinRange);
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Events returned: 2
Created event 1 included: true
Created event 2 included: true
All returned events in range: true
Creating a Statement with Line Items¶
REST API endpoint
POST /cx/v2/action/setStatement — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.StatementsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.EmbeddedCustomer;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.LineItemDTO;
import com.gp.cx.sdk.model.StatementDTO;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Collections;
public class CreateStatementExample {
public static void main(String[] args) {
StatementsApi statementsApi = client.getStatementsApi();
LineItemDTO lineItem1 = new LineItemDTO()
.description("Monthly Service Fee")
.amount(5000L)
.lineItemReference("REF-001")
.date(LocalDate.parse("2026-06-25"));
EmbeddedCustomer embedded = new EmbeddedCustomer()
.customer(new IDWrapper().id("customer-uuid-here"));
StatementDTO statementRequest = new StatementDTO()
.currency(StatementDTO.CurrencyEnum.USD)
.totalAmount(new BigDecimal("5000"))
.statementDateTime(OffsetDateTime.parse("2026-06-25T12:00:00Z"))
.customerMessage("Thank you for your business")
.dueInFullDateTime(OffsetDateTime.parse("2026-07-25T12:00:00Z"))
.embedded(embedded)
.lineItems(Collections.singletonList(lineItem1));
try {
StatementDTO statementCreated = statementsApi.setStatement(statementRequest);
System.out.println("Statement created: " + statementCreated.getId());
System.out.println("Total line items: " + statementCreated.getLineItems().size());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Statement created: stmt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Total line items: 1
Creating a Payment Request¶
REST API endpoint
POST /cx/v2/action/createPaymentRequest — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.PaymentRequestsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.EmbeddedCustomer;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.LineItemDTO;
import com.gp.cx.sdk.model.OptionalDataDTO;
import com.gp.cx.sdk.model.PaymentRequestDTO;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
public class CreatePaymentRequestExample {
public static void main(String[] args) {
PaymentRequestsApi paymentRequestsApi = client.getPaymentRequestsApi();
List<LineItemDTO> lineItems = new ArrayList<>();
lineItems.add(new LineItemDTO()
.lineItemReference("1-31663098")
.date(OffsetDateTime.parse("2024-02-09T15:55:33.885Z").toLocalDate())
.amount(499995L)
.description("CREDIT!"));
OptionalDataDTO optionalData = new OptionalDataDTO()
.taxAmount(new BigDecimal("353"))
.poNumber("123456789")
.invoiceNumber("8880326514565")
.destinationPostalCode("84663")
.clerkId("Al080-Jahn Doe");
IDWrapper idWrapper = new IDWrapper().id("customer-uuid-here");
EmbeddedCustomer embedded = new EmbeddedCustomer().customer(idWrapper);
PaymentRequestDTO paymentRequest = new PaymentRequestDTO()
.currency(PaymentRequestDTO.CurrencyEnum.USD)
.totalAmount(new BigDecimal("499995"))
.paymentRequestDateTime(OffsetDateTime.parse("2020-02-25T09:30:00.000Z"))
.customerMessage("Thank you for visiting RBM Alpharetta.")
.dueInFullDateTime(OffsetDateTime.parse("2020-03-25T09:30:00.000Z"))
.viewDetailUrl("https://google.com")
.description("Generic Description")
.optionalData(optionalData)
.lineItems(lineItems)
.embedded(embedded);
try {
PaymentRequestDTO paymentRequestCreated =
paymentRequestsApi.createPaymentRequest(paymentRequest);
System.out.println("Payment request created: " + paymentRequestCreated.getId());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Payment request created: pr-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Discarding a Payment Request¶
Create a payment request, then discard it with forceDiscard=true:
import com.gp.cx.sdk.api.PaymentRequestsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.DiscardActionDTO;
import com.gp.cx.sdk.model.EmbeddedCustomer;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.LineItemDTO;
import com.gp.cx.sdk.model.OptionalDataDTO;
import com.gp.cx.sdk.model.PaymentRequestDTO;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
public class DiscardPaymentRequestExample {
public static void main(String[] args) {
PaymentRequestsApi paymentRequestsApi = client.getPaymentRequestsApi();
try {
PaymentRequestDTO request = buildValidPaymentRequestFromJson("customer-uuid-here");
PaymentRequestDTO created = paymentRequestsApi.createPaymentRequest(request);
DiscardActionDTO discardReq = new DiscardActionDTO()
.id(created.getId())
.forceDiscard(true);
DiscardActionDTO response = paymentRequestsApi.discardPaymentRequest(discardReq);
System.out.println("Discarded payment request ID: " + created.getId());
System.out.println("Response id is null: " + (response.getId() == null));
System.out.println("Response forceDiscard is null: " + (response.getForceDiscard() == null));
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
private static PaymentRequestDTO buildValidPaymentRequestFromJson(String createdCustomerId) {
List<LineItemDTO> lineItems = new ArrayList<>();
lineItems.add(new LineItemDTO()
.lineItemReference("1-31663098")
.date(OffsetDateTime.parse("2024-02-09T15:55:33.885Z").toLocalDate())
.amount(499995L)
.description("CREDIT!"));
OptionalDataDTO optionalData = new OptionalDataDTO()
.taxAmount(new BigDecimal("353"))
.poNumber("123456789")
.invoiceNumber("8880326514565")
.destinationPostalCode("84663")
.clerkId("Al080-Jahn Doe");
IDWrapper idWrapper = new IDWrapper().id(createdCustomerId);
EmbeddedCustomer embedded = new EmbeddedCustomer().customer(idWrapper);
return new PaymentRequestDTO()
.currency(PaymentRequestDTO.CurrencyEnum.USD)
.totalAmount(new BigDecimal("499995"))
.paymentRequestDateTime(OffsetDateTime.parse("2020-02-25T09:30:00.000Z"))
.customerMessage("Thank you for visiting RBM Alpharetta.")
.dueInFullDateTime(OffsetDateTime.parse("2020-03-25T09:30:00.000Z"))
.viewDetailUrl("https://google.com")
.description("Generic Description")
.optionalData(optionalData)
.lineItems(lineItems)
.embedded(embedded);
}
}
Expected output:
Discarded payment request ID: pr-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Response id is null: true
Response forceDiscard is null: true
Creating a Quote¶
Generate a customer-facing service quote:
REST API endpoint
POST /cx/v2/action/createQuote — See the Swagger UI for the full request/response schema.
import com.gp.cx.sdk.api.QuotesApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.CreateQuoteDTO;
import com.gp.cx.sdk.model.EmbeddedCustomer;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.LineItemDTO;
import com.gp.cx.sdk.model.MetadataBodyDto;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Collections;
public class CreateQuoteExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
QuotesApi quotesApi = client.getQuotesApi();
String customerId = "customer-uuid-here";
LineItemDTO lineItem = new LineItemDTO()
.lineItemReference("REF-12345")
.date(LocalDate.parse("2024-10-08"))
.description("Payment Line Item")
.amount(1000L)
.attachmentUrl("https://www.globalpayments.com");
EmbeddedCustomer embedded = new EmbeddedCustomer()
.customer(new IDWrapper().id(customerId));
MetadataBodyDto myMetadata = new MetadataBodyDto();
myMetadata.setExternalId("ID-12345");
myMetadata.setData(Collections.singletonMap("testKey", "testValue"));
CreateQuoteDTO request = new CreateQuoteDTO()
.lineItems(Collections.singletonList(lineItem))
.totalAmount(BigDecimal.valueOf(1000))
.viewDetailUrl("https://www.google.com")
.expiryDateTime(OffsetDateTime.parse("2025-12-25T00:00:00.000Z"))
.customerMessage("Test")
.title("Test Title")
.termsAndConditions("# Markdown")
.embedded(embedded)
.myMetadata(myMetadata);
try {
CreateQuoteDTO response = quotesApi.createQuoteForCustomer(request);
System.out.println("Quote ID: " + response.getId());
System.out.println("Total amount: " + response.getTotalAmount());
System.out.println("View URL: " + response.getViewDetailUrl());
System.out.println("Expiry: " + response.getExpiryDateTime());
System.out.println("Customer message: " + response.getCustomerMessage());
System.out.println("Title: " + response.getTitle());
System.out.println("Terms: " + response.getTermsAndConditions());
System.out.println("Customer ID matches: "
+ customerId.equals(response.getEmbedded().getCustomer().getId()));
System.out.println("Metadata testKey: " + response.getMyMetadata().getData().get("testKey"));
System.out.println("Status: " + response.getStatus());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Quote ID: quote-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Total amount: 1000
View URL: https://www.google.com
Expiry: 2025-12-25T00:00Z
Customer message: Test
Title: Test Title
Terms: # Markdown
Customer ID matches: true
Metadata testKey: testValue
Status: CREATED
Discarding a Quote¶
Create a quote, then discard it by ID:
import com.gp.cx.sdk.api.QuotesApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.CreateQuoteDTO;
import com.gp.cx.sdk.model.DiscardActionDTO;
import com.gp.cx.sdk.model.EmbeddedCustomer;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.LineItemDTO;
import com.gp.cx.sdk.model.MetadataBodyDto;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Collections;
public class DiscardQuoteExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
QuotesApi quotesApi = client.getQuotesApi();
String customerId = "customer-uuid-here";
try {
CreateQuoteDTO request = new CreateQuoteDTO();
LineItemDTO lineItem = new LineItemDTO();
lineItem.setLineItemReference("REF-VALID-DISCARD");
lineItem.setDate(LocalDate.now());
lineItem.setDescription("Valid Discard Test");
lineItem.setAmount(100L);
lineItem.setAttachmentUrl("https://www.globalpayments.com");
request.setLineItems(Collections.singletonList(lineItem));
request.setTotalAmount(BigDecimal.valueOf(100));
request.setViewDetailUrl("https://www.google.com");
request.setExpiryDateTime(OffsetDateTime.now().plusDays(1));
request.setCustomerMessage("Test");
request.setTitle("Test Title");
request.setTermsAndConditions("# Markdown");
EmbeddedCustomer embedded = new EmbeddedCustomer();
IDWrapper customer = new IDWrapper();
customer.setId(customerId);
embedded.setCustomer(customer);
request.setEmbedded(embedded);
MetadataBodyDto myMetadata = new MetadataBodyDto();
myMetadata.setExternalId("ID-VALID-DISCARD");
myMetadata.setData(Collections.singletonMap("testKey", "testValue"));
request.setMyMetadata(myMetadata);
CreateQuoteDTO createdQuote = quotesApi.createQuoteForCustomer(request);
DiscardActionDTO discardRequest = new DiscardActionDTO();
discardRequest.setId(createdQuote.getId());
discardRequest.setForceDiscard(false);
DiscardActionDTO response = quotesApi.discardQuote(discardRequest);
System.out.println("Created quote ID: " + createdQuote.getId());
System.out.println("Discard response id is null: " + (response.getId() == null));
System.out.println("Discard response forceDiscard is null: " + (response.getForceDiscard() == null));
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Created quote ID: quote-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Discard response id is null: true
Discard response forceDiscard is null: true
Using Custom Metadata¶
Attach arbitrary key-value metadata to API requests using MetadataBodyDto:
import com.gp.cx.sdk.model.MetadataBodyDto;
import java.util.HashMap;
import java.util.Map;
public class MetadataExample {
public static void main(String[] args) {
Map<String, String> metadataMap = new HashMap<>();
metadataMap.put("source", "onboarding-portal");
metadataMap.put("campaign", "summer-2024");
metadataMap.put("internalRef", "REF-9876");
MetadataBodyDto metadata = new MetadataBodyDto();
metadata.setExternalId("REF-9876");
metadata.setData(metadataMap);
// Metadata can be passed when creating or updating resources.
// Refer to the specific API method signature for where MetadataBodyDto is accepted.
}
}
Tip
Metadata is useful for correlating CX Platform entities with records in your own systems. Use consistent key naming conventions across your integration.
Triggering Actions¶
Use ActionsApi to trigger and manage platform-level actions:
REST API endpoint
See the Swagger UI for available action endpoints and their schemas.
import com.gp.cx.sdk.api.ActionsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
public class ActionsExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
ActionsApi actionsApi = client.getActionsApi();
try {
// Refer to the SDK Javadoc for available action methods and required parameters.
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Info
Refer to the SDK Javadoc for the full list of methods on ActionsApi.
Configuration Management¶
Use ConfigApi to read and update location configuration settings:
REST API endpoint
See the Swagger UI for available configuration endpoints and their schemas.
import com.gp.cx.sdk.api.ConfigApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
public class ConfigExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
ConfigApi configApi = client.getConfigApi();
try {
// Refer to the SDK Javadoc for available configuration methods and required parameters.
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Info
Refer to the SDK Javadoc for the full list of methods on ConfigApi.
Working with Forms¶
Use FormsApi to retrieve form definitions and submit form data:
REST API endpoint
See the Swagger UI for available form endpoints and their schemas.
import com.gp.cx.sdk.api.FormsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
public class FormsExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
FormsApi formsApi = client.getFormsApi();
try {
// Refer to the SDK Javadoc for available form methods and required parameters.
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Creating a Form for a Customer¶
import com.gp.cx.sdk.api.FormsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.CreateFormDTO;
import com.gp.cx.sdk.model.EmbeddedFormTypeRequestForCustomer;
import com.gp.cx.sdk.model.FormTypeIdWrapper;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.MetadataBodyDto;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
public class CreateFormForCustomerExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
FormsApi formsApi = client.getFormsApi();
String customerId = "customer-uuid-here";
try {
CreateFormDTO request = new CreateFormDTO();
request.setConfigOverrides(Collections.singletonMap("on_createForm_sendMessage_enabled", "true"));
MetadataBodyDto myMetadata = new MetadataBodyDto();
myMetadata.setExternalId("ID-12345");
myMetadata.setData(Collections.singletonMap("additionalProp1", "string"));
request.setMyMetadata(myMetadata);
Map<String, String> formLabel = new HashMap<>();
formLabel.put("EN", "Form Label");
request.setFormLabel(formLabel);
EmbeddedFormTypeRequestForCustomer embedded = new EmbeddedFormTypeRequestForCustomer();
FormTypeIdWrapper formType = new FormTypeIdWrapper();
formType.setFormTypeIdentifier("XMS-Covid19");
embedded.setFormType(formType);
IDWrapper customer = new IDWrapper();
customer.setId(customerId);
embedded.setCustomer(customer);
request.setEmbedded(embedded);
CreateFormDTO response = formsApi.createFormForCustomer(request);
System.out.println("Created form ID: " + response.getId());
System.out.println("Form label matches: " + formLabel.equals(response.getFormLabel()));
System.out.println("Metadata external ID: " + response.getMyMetadata().getExternalId());
System.out.println("Form type identifier: " + response.getEmbedded().getFormType().getFormTypeIdentifier());
System.out.println("Customer ID matches: " + customerId.equals(response.getEmbedded().getCustomer().getId()));
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Created form ID: frm-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Form label matches: true
Metadata external ID: ID-12345
Form type identifier: XMS-Covid19
Customer ID matches: true
Discarding a Form¶
import com.gp.cx.sdk.api.FormsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.CreateFormDTO;
import com.gp.cx.sdk.model.DiscardActionDTO;
import com.gp.cx.sdk.model.EmbeddedFormTypeRequestForCustomer;
import com.gp.cx.sdk.model.FormTypeIdWrapper;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.MetadataBodyDto;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
public class DiscardFormExample {
public static void main(String[] args) {
FormsApi formsApi = client.getFormsApi();
String customerId = "customer-uuid-here";
try {
CreateFormDTO createRequest = new CreateFormDTO();
createRequest.setConfigOverrides(Collections.singletonMap("on_createForm_sendMessage_enabled", "true"));
MetadataBodyDto myMetadata = new MetadataBodyDto();
myMetadata.setExternalId("ID-12345");
myMetadata.setData(Collections.singletonMap("additionalProp1", "string"));
createRequest.setMyMetadata(myMetadata);
Map<String, String> formLabel = new HashMap<>();
formLabel.put("EN", "Form Label");
createRequest.setFormLabel(formLabel);
EmbeddedFormTypeRequestForCustomer embedded = new EmbeddedFormTypeRequestForCustomer();
FormTypeIdWrapper formType = new FormTypeIdWrapper();
formType.setFormTypeIdentifier("XMS-Covid19");
embedded.setFormType(formType);
IDWrapper customer = new IDWrapper();
customer.setId(customerId);
embedded.setCustomer(customer);
createRequest.setEmbedded(embedded);
CreateFormDTO createdForm = formsApi.createFormForCustomer(createRequest);
DiscardActionDTO discardRequest = new DiscardActionDTO()
.id(createdForm.getId())
.forceDiscard(true);
DiscardActionDTO response = formsApi.discardForm(discardRequest);
System.out.println("Created form ID: " + createdForm.getId());
System.out.println("Discard response id is null: " + (response.getId() == null));
System.out.println("Discard response forceDiscard is null: " + (response.getForceDiscard() == null));
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Created form ID: frm-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Discard response id is null: true
Discard response forceDiscard is null: true
Setting Form Defaults for Service Location¶
import com.gp.cx.sdk.api.FormsApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.EmbeddedFormType;
import com.gp.cx.sdk.model.FormDefaultsDTO;
import com.gp.cx.sdk.model.FormElement;
import com.gp.cx.sdk.model.FormTypeIdWrapper;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class SetFormDefaultsForServiceLocationExample {
public static void main(String[] args) {
FormsApi formsApi = client.getFormsApi();
try {
FormDefaultsDTO request = new FormDefaultsDTO();
Map<String, String> formLabel = new HashMap<>();
formLabel.put("EN", "Form Label");
request.setFormLabel(formLabel);
FormElement element1 = new FormElement();
element1.setId("reasonForVisit");
element1.setValue("required \n multiline");
FormElement element2 = new FormElement();
element2.setId("agreeCheckBoxToggle");
element2.setValue(true);
List<FormElement> formElementData = new ArrayList<>();
formElementData.add(element1);
formElementData.add(element2);
request.setFormElementData(formElementData);
EmbeddedFormType embedded = new EmbeddedFormType();
embedded.setFormType(new FormTypeIdWrapper());
embedded.getFormType().setFormTypeIdentifier("FormDefaultsAutomatedV03032022");
request.setEmbedded(embedded);
FormDefaultsDTO response = formsApi.setFormDefaultsForServiceLocation(request);
System.out.println("Form elements returned: " + response.getFormElementData().size());
System.out.println("First element ID: " + response.getFormElementData().get(0).getId());
System.out.println("Second element ID: " + response.getFormElementData().get(1).getId());
System.out.println("Form type identifier: " + response.getEmbedded().getFormType().getFormTypeIdentifier());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Form elements returned: 2
First element ID: reasonForVisit
Second element ID: agreeCheckBoxToggle
Form type identifier: FormDefaultsAutomatedV03032022
Info
Refer to the SDK Javadoc for the full list of methods on FormsApi.
Queue Management¶
Use QueueApi to manage and process service queue entries:
REST API endpoint
See the Swagger UI for available queue endpoints and their schemas.
import com.gp.cx.sdk.api.QueueApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
public class QueueExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
QueueApi queueApi = client.getQueueApi();
try {
// Refer to the SDK Javadoc for available queue methods and required parameters.
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Info
Refer to the SDK Javadoc for the full list of methods on QueueApi.
Managing Resources¶
Use ResourcesApi to create, retrieve, and manage platform resources:
REST API endpoint
See the Swagger UI for available resource endpoints and their schemas.
import com.gp.cx.sdk.api.ResourcesApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
public class ResourcesExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
ResourcesApi resourcesApi = client.getResourcesApi();
try {
// Refer to the SDK Javadoc for available resource methods and required parameters.
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Setting a Resource¶
import com.gp.cx.sdk.api.ResourcesApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ChannelEmailDTO;
import com.gp.cx.sdk.model.ChannelPhoneDTO;
import com.gp.cx.sdk.model.ChannelUsageType;
import com.gp.cx.sdk.model.EmbeddedServiceLocation;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.MetadataBodyDto;
import com.gp.cx.sdk.model.ResourceDTO;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashSet;
public class SetResourceExample {
public static void main(String[] args) {
ResourcesApi resourcesApi = client.getResourcesApi();
String serviceLocationId = "service-location-uuid-here";
try {
ResourceDTO resource = new ResourceDTO();
resource.setName("Resource Name");
resource.setDescription("Resource Description");
resource.setImageUrl("http://website.com/image.png");
resource.setTags(new HashSet<>(Arrays.asList("cx-provider", "hairdresser")));
resource.setInactive(true);
ChannelEmailDTO email = new ChannelEmailDTO();
email.setValue("test@email.com");
resource.setPrimaryEmail(email);
ChannelPhoneDTO phone = new ChannelPhoneDTO();
phone.setValue("+18015555555");
resource.setPrimaryPhone(phone);
resource.setColor("#FFFFFF");
EmbeddedServiceLocation embedded = new EmbeddedServiceLocation();
IDWrapper serviceLocation = new IDWrapper();
serviceLocation.setId(serviceLocationId);
embedded.setServiceLocation(serviceLocation);
resource.setEmbedded(embedded);
MetadataBodyDto metadata = new MetadataBodyDto();
metadata.setExternalId("externalId");
resource.setMyMetadata(metadata);
ResourceDTO response = resourcesApi.setResource(resource);
System.out.println("Resource ID: " + response.getId());
System.out.println("Name: " + response.getName());
System.out.println("Description: " + response.getDescription());
System.out.println("Image URL: " + response.getImageUrl());
System.out.println("Color: " + response.getColor());
System.out.println("Inactive: " + response.getInactive());
System.out.println("Primary email: " + response.getPrimaryEmail().getValue());
System.out.println("Primary phone: " + response.getPrimaryPhone().getValue());
System.out.println("Primary phone usage is PRIMARY: "
+ Collections.singleton(ChannelUsageType.PRIMARY).equals(response.getPrimaryPhone().getChannelUsage()));
System.out.println("Service location ID: " + response.getEmbedded().getServiceLocation().getId());
System.out.println("Primary phone embedded customer ID matches resource ID: "
+ response.getId().equals(response.getPrimaryPhone().getEmbedded().getCustomer().getId()));
System.out.println("Primary email embedded customer ID matches resource ID: "
+ response.getId().equals(response.getPrimaryEmail().getEmbedded().getCustomer().getId()));
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Resource ID: res-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Name: Resource Name
Description: Resource Description
Image URL: http://website.com/image.png
Color: #FFFFFF
Inactive: true
Primary email: test@email.com
Primary phone: +18015555555
Primary phone usage is PRIMARY: true
Service location ID: service-location-uuid-here
Primary phone embedded customer ID matches resource ID: true
Primary email embedded customer ID matches resource ID: true
Getting a Resource by ID¶
import com.gp.cx.sdk.api.ResourcesApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ChannelUsageType;
import com.gp.cx.sdk.model.ResourceDTO;
import java.util.Collections;
public class GetResourceByIdExample {
public static void main(String[] args) {
ResourcesApi resourcesApi = client.getResourcesApi();
String resourceId = "resource-uuid-here";
try {
ResourceDTO resource = resourcesApi.getResourceById(resourceId);
System.out.println("Resource ID matches: " + resourceId.equals(resource.getId()));
System.out.println("Name: " + resource.getName());
System.out.println("Description: " + resource.getDescription());
System.out.println("Image URL: " + resource.getImageUrl());
System.out.println("Tags: " + resource.getTags());
System.out.println("Inactive: " + resource.getInactive());
System.out.println("Primary email: " + resource.getPrimaryEmail().getValue());
System.out.println("Primary phone: " + resource.getPrimaryPhone().getValue());
System.out.println("Primary phone usage is PRIMARY: "
+ Collections.singleton(ChannelUsageType.PRIMARY).equals(resource.getPrimaryPhone().getChannelUsage()));
System.out.println("Color: " + resource.getColor());
System.out.println("Metadata external ID: " + resource.getMyMetadata().getExternalId());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Resource ID matches: true
Name: Test Resource Name
Description: Test Resource Description
Image URL: http://cx-test.com/image.png
Tags: [cx-provider, hairdresser]
Inactive: true
Primary email: test@email.com
Primary phone: +18015555555
Primary phone usage is PRIMARY: true
Color: #FFFFFF
Metadata external ID: externalId
Getting All Resources¶
import com.gp.cx.sdk.api.ResourcesApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ResourceDTO;
import java.util.List;
public class GetAllResourcesExample {
public static void main(String[] args) {
ResourcesApi resourcesApi = client.getResourcesApi();
String expectedResourceId = "resource-uuid-here";
try {
List<ResourceDTO> resources = resourcesApi.getAllResources();
ResourceDTO found = resources.stream()
.filter(r -> expectedResourceId.equals(r.getId()))
.findFirst()
.orElse(null);
System.out.println("Resources returned: " + resources.size());
System.out.println("Expected resource found: " + (found != null));
if (found != null) {
System.out.println("Name: " + found.getName());
System.out.println("Description: " + found.getDescription());
System.out.println("Image URL: " + found.getImageUrl());
System.out.println("Primary email: " + found.getPrimaryEmail().getValue());
System.out.println("Primary phone: " + found.getPrimaryPhone().getValue());
System.out.println("Color: " + found.getColor());
System.out.println("Metadata external ID: " + found.getMyMetadata().getExternalId());
}
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Expected output:
Resources returned: 5
Expected resource found: true
Name: Test Resource Name
Description: Test Resource Description
Image URL: http://cx-test.com/image.png
Primary email: test@email.com
Primary phone: +18015555555
Color: #FFFFFF
Metadata external ID: externalId
Deleting a Resource by ID¶
import com.gp.cx.sdk.api.ResourcesApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ChannelEmailDTO;
import com.gp.cx.sdk.model.ChannelPhoneDTO;
import com.gp.cx.sdk.model.EmbeddedServiceLocation;
import com.gp.cx.sdk.model.IDWrapper;
import com.gp.cx.sdk.model.MetadataBodyDto;
import com.gp.cx.sdk.model.ResourceDTO;
import java.util.Arrays;
import java.util.HashSet;
public class DeleteResourceByIdExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
ResourcesApi resourcesApi = client.getResourcesApi();
String serviceLocationId = "service-location-uuid-here";
try {
ResourceDTO created = resourcesApi.setResource(buildTestResource(serviceLocationId));
String resourceId = created.getId();
try {
resourcesApi.deleteResourceById(resourceId);
try {
resourcesApi.getResourceById(resourceId);
System.out.println("Resource still exists after delete: " + resourceId);
} catch (CxSdkClientException ex) {
System.out.println("Deleted resource ID: " + resourceId);
System.out.println("Get after delete returned 404: " + "404".equals(ex.getApiErrorCode()));
System.out.println("Error message: " + ex.getApiErrorMessage());
System.err.println("API call failed:");
System.err.println(" Status code: " + ex.getStatusCode());
System.err.println(" Error category: " + ex.getErrorCategory());
System.err.println(" API error code: " + ex.getApiErrorCode());
System.err.println(" API message: " + ex.getApiErrorMessage());
System.err.println(" Retryable: " + ex.isRetryable());
System.err.println(" Response body: " + ex.getResponseBody());
}
} catch (CxSdkClientException ex) {
boolean referenced = ex.getStatusCode() == 400
&& (ex.getMessage().contains("is required for Event Template")
|| ex.getMessage().contains("is required for event"));
System.out.println("Delete blocked because resource is referenced: " + referenced);
System.out.println("Status: " + ex.getStatusCode());
System.out.println("Message: " + ex.getMessage());
System.err.println("API call failed:");
System.err.println(" Status code: " + ex.getStatusCode());
System.err.println(" Error category: " + ex.getErrorCategory());
System.err.println(" API error code: " + ex.getApiErrorCode());
System.err.println(" API message: " + ex.getApiErrorMessage());
System.err.println(" Retryable: " + ex.isRetryable());
System.err.println(" Response body: " + ex.getResponseBody());
}
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
private static ResourceDTO buildTestResource(String serviceLocationId) {
ResourceDTO resource = new ResourceDTO();
resource.setName("Test Resource Name");
resource.setDescription("Test Resource Description");
resource.setImageUrl("http://cx-test.com/image.png");
resource.setTags(new HashSet<>(Arrays.asList("cx-provider", "hairdresser")));
resource.setInactive(true);
ChannelEmailDTO email = new ChannelEmailDTO();
email.setValue("test@email.com");
resource.setPrimaryEmail(email);
ChannelPhoneDTO phone = new ChannelPhoneDTO();
phone.setValue("+18015555555");
resource.setPrimaryPhone(phone);
resource.setColor("#FFFFFF");
EmbeddedServiceLocation embedded = new EmbeddedServiceLocation();
IDWrapper serviceLocation = new IDWrapper();
serviceLocation.setId(serviceLocationId);
embedded.setServiceLocation(serviceLocation);
resource.setEmbedded(embedded);
MetadataBodyDto metadata = new MetadataBodyDto();
metadata.setExternalId("externalId");
resource.setMyMetadata(metadata);
return resource;
}
}
Expected output:
Deleted resource ID: res-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Get after delete returned 404: true
Info
Refer to the SDK Javadoc for the full list of methods on ResourcesApi.
Handling Secure Data¶
Use SecureDataApi to store and retrieve sensitive data in the platform's
secure vault:
REST API endpoint
See the Swagger UI for available secure-data endpoints and their schemas.
import com.gp.cx.sdk.api.SecureDataApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
public class SecureDataExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
SecureDataApi secureDataApi = client.getSecureDataApi();
try {
// Refer to the SDK Javadoc for available secure data methods and required parameters.
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Info
Refer to the SDK Javadoc for the full list of methods on SecureDataApi.
UI Configuration¶
Use UiApi to manage UI elements and configuration for the CX Platform
interface:
REST API endpoint
See the Swagger UI for available UI endpoints and their schemas.
import com.gp.cx.sdk.api.UiApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
public class UiConfigExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
UiApi uiApi = client.getUiApi();
try {
// Refer to the SDK Javadoc for available UI methods and required parameters.
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
Info
Refer to the SDK Javadoc for the full list of methods on UiApi.
Pagination¶
Coming Soon
Pagination helpers are not yet available in the current SDK version. Once pagination support is added, examples will appear here showing how to iterate through paged results. In the meantime, refer to the Swagger UI for the query parameters supported by individual list endpoints.
Batch and Bulk Operations¶
The CX Platform API processes each record individually — there are no dedicated bulk endpoints. To create or update multiple records, call the appropriate API method in sequence and handle errors per record so one failure does not stop the entire batch:
import com.gp.cx.sdk.api.CustomersApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.CustomerDTO;
import java.util.Arrays;
import java.util.List;
public class BulkCustomerExample {
public static void main(String[] args) {
CxSdkClient client = new CxSdkClient.Builder()
.apiKey(System.getenv("CX_LOCATION_API_KEY"))
.baseUrl("https://cx2-main.pit.cxgp.us")
.build();
CustomersApi customersApi = client.getCustomersApi();
List<CustomerDTO> customers = Arrays.asList(
new CustomerDTO().givenName("Alice").familyName("Smith"),
new CustomerDTO().givenName("Bob").familyName("Jones")
);
for (CustomerDTO customerRequest : customers) {
try {
CustomerDTO created = customersApi.setCustomer(customerRequest);
System.out.println("Created: " + created.getDisplayCustomerId());
} catch (CxSdkClientException e) {
System.err.println("API call failed:");
System.err.println(" Status code: " + e.getStatusCode());
System.err.println(" Error category: " + e.getErrorCategory());
System.err.println(" API error code: " + e.getApiErrorCode());
System.err.println(" API message: " + e.getApiErrorMessage());
System.err.println(" Retryable: " + e.isRetryable());
System.err.println(" Response body: " + e.getResponseBody());
}
}
}
}
Tip
Because the SDK is synchronous, consider wrapping calls in a
CompletableFuture with a dedicated thread pool for parallel processing.
See the FAQ for an async wrapper example.
Next Steps¶
- Review Error Handling for production-grade error patterns
- Check the FAQ for common questions
- Browse the REST API Overview for the full endpoint reference
Available API Modules¶
The CxSdkClient provides access to 15 API modules via getter methods:
| Getter Method | Description |
|---|---|
getActionsApi() |
Trigger and manage actions |
getApiKeyApi() |
API key management |
getConfigApi() |
Configuration settings |
getCustomersApi() |
Customer CRUD operations |
getEventsApi() |
Event management |
getFormsApi() |
Form definitions and submissions |
getPaymentRequestsApi() |
Payment request operations |
getQuotesApi() |
Quote generation and management |
getQueueApi() |
Queue management |
getResourcesApi() |
Resource management |
getSecureDataApi() |
Secure/sensitive data handling |
getServiceLocationApi() |
Service location management |
getStatementsApi() |
Statement and billing operations |
getUiApi() |
UI configuration and elements |