Salesforce SDK

Create a Conversive Account

Use createConversiveAccount() during onboarding when the org is not yet linked to an existing Conversive account.

What this API does

If successful, this method:

  • provisions a new Conversive account
  • returns a response wrapper with status information
  • includes a detailed value payload
  • sends an email to the logged-in user’s email address with the API key

That API key is then used in upsertEnvironmentSettings().

Method signature

public static ConversiveAPI.ConversiveAPIResponse createConversiveAccount()

Inputs

This API takes no input parameters.

Response type

public class ConversiveAPIResponse {
    public String response;         // SUCCESS / ERROR
    public String responseMessage;  // Human-readable message
    public Object value;            // Result returned from account creation
}

Response fields

FieldTypeDescription
responseStringIndicates success or failure
responseMessageStringHuman-readable outcome
valueObjectSerialized JSON payload containing detailed account creation job output

value payload structure

The Confluence page documents the value field as serialized JSON with these fields:

FieldDescription
jobTypeJob type executed. For this API, the documented value is CREATE_ACCOUNT.
successWhether account creation succeeded at the service level
statusCodeHTTP or service status code
responseCodePlatform-specific response code
messageHuman-readable service message
accountIdNewly created Conversive account ID
userIdUser ID associated with the created account
accessTokenAccess token, if returned
refreshTokenRefresh token, if returned
resendAccessCodeResend or access code reference, if returned
rawBodyRaw response body returned by the platform

Example

try {
    ConversiveAPI.ConversiveAPIResponse resp =
        ConversiveAPI.createConversiveAccount();
    System.debug('response = ' + resp.response);
    System.debug('responseMessage = ' + resp.responseMessage);
    System.debug('value = ' + resp.value);
} catch (Exception e) {
    System.debug('ERROR = ' + e.getMessage());
    System.debug('STACK = ' + e.getStackTraceString());
}

Example success response

response = 'SUCCESS'
responseMessage = 'Conversive account created successfully'

Example value payload

{
  "jobType": "CREATE_ACCOUNT",
  "success": true,
  "statusCode": 200,
  "responseCode": "SUCCESS",
  "message": "Account created successfully",
  "accountId": 12345,
  "userId": 67890,
  "accessToken": "sample-access-token",
  "refreshToken": "sample-refresh-token",
  "resendAccessCode": "ABC123",
  "rawBody": "{...}"
}

Example error response

response = 'ERROR'
responseMessage = 'Unable to create Conversive account'

Error handling guidance

Documented error behavior

The page documents the following error pattern:

  • response = 'ERROR'
  • responseMessage explains the failure
  • value may still contain diagnostic fields such as:
    • statusCode
    • responseCode
    • message
    • rawBody

What a developer should do

  • inspect both responseMessage and value
  • log the raw value payload during troubleshooting
  • confirm the logged-in user has a valid email address
  • check the inbox of the logged-in user for the API key email after success
1

Deploy the SDK

Make sure metadata is deployed and the org is ready for setup.

2

Call createConversiveAccount()

Run this only if the org is not already linked to a Conversive account.

3

Check the user’s email

The API key is delivered to the logged-in user’s email address.

4

Save environment settings

Call upsertEnvironmentSettings() with the received API key and the correct endpoint.

5

Verify setup

Call getConversiveBalance() or getConversivePlanDetails() to confirm the environment is working.

Best practices

  • call this method once per org onboarding flow
  • do not call it repeatedly if the account already exists
  • keep the returned value payload for diagnostics
  • configure the environment immediately after receiving the API key