Bulk Validation Methods

The /v1/bulk/validate endpoint validates address, phone, and email items in one request, returning keyed results with status and advice for each item.

The /v1/bulk/validate endpoint validates addresses, phone numbers and email addresses in a single request. Each item is validated the same way as with the separate address, phone and email endpoints, and every result is returned under the identifier you chose for it.

Key Points

Send any combination of addresses, phone numbers and email addresses in one request, for example two addresses, one phone number and three email addresses.
Every item is keyed by an identifier you choose, such as billing, mobile or a record ID. The response uses the same identifiers.
Each item uses the same input fields as the single endpoints and returns the same output as those endpoints, including validation advice (GREEN, AMBER or RED).
An address without a country is validated against your default country, like the address validation endpoint does.

Authentication

The validateBulk endpoint requires authentication via Salesforce OAuth 2.0. Requests must include a valid OAuth access token in the Authorization header.

For detailed authentication steps, refer to: Salesforce Authentication Guide.

Method Signature

HTTP

POST /services/apexrest/recordval/v1/bulk/validate

Parameters

Type	Variable	Description
BulkValidationInput_v1	`bulkInput`	The structured input object containing the addresses, phone numbers and email addresses to validate.

Input

BulkValidationInput_v1

Field	Type	Required	Description
`addresses`	Map of String to AddressValidationInput_v1	No	The addresses to validate, keyed by an identifier of your choice.
`phones`	Map of String to PhoneValidationInput_v1	No	The phone numbers to validate, keyed by an identifier of your choice.
`emails`	Map of String to EmailValidationInput_v1	No	The email addresses to validate, keyed by an identifier of your choice.
`note`	String	No	A custom note for logging or reference purposes. Applies to the whole request. When left empty, `api` is used.

The request must contain at least one address, phone number or email address. Identifiers can not be empty.

Address item: AddressValidationInput_v1

Field	Type	Required	Description
`street`	String	No	The street address to be validated.
`housenumber`	String	No	The primary house number of the address.
`housenumberAddition`	String	No	Additional details for the house number (e.g., unit or suite).
`postalCode`	String	No	The postal or ZIP code for the address.
`city`	String	No	The city where the address is located.
`state`	String	No	The state or region of the address.
`country`	String	No	The country code or name for the address. When left empty, the default country is used.
`latitude`	String	No	The latitude coordinate, used for geocoding if provided.
`longitude`	String	No	The longitude coordinate, used for geocoding if provided.
`addressOptions`	AddressOptions_v1	No	Customization options for address parsing and validation. See below.

The fields note, convertToSuggestionStatus and addressOptions.includeMunicipalityFromAddresses are not supported per item in a bulk request and are ignored. Use the note on BulkValidationInput_v1 instead.

AddressOptions_v1

Field	Type	Required	Description
`housenumber`	Boolean	No	Return the house number as a separate field instead of as part of the street. Default: `false`.
`housenumberAddition`	Boolean	No	Return the house number addition as a separate field. Default: `false`.
`geocode`	Boolean	No	Return latitude and longitude for the address. Default: `false`.
`addressSeparator`	String	No	The separator used between address lines in `fullAddress`. When left empty, the separator from your Verify settings is used.

Phone item: PhoneValidationInput_v1

Field	Type	Required	Description
`phoneNumber`	String	Yes	The phone number to be validated.
`country`	String	No	The country associated with the phone number for validation.
`format`	PhoneFormat_v1	No	The format in which the validated phone number is returned: `E164`, `INTERNATIONAL`, `NATIONAL` or `RFC3966`. Default: `E164`.

Email item: EmailValidationInput_v1

Field	Type	Required	Description
`emailAddress`	String	Yes	The email address to be validated.

Example Request

JSON

{
  "note": "Validating a new Lead",
  "addresses": {
    "billing": {
      "street": "Stationsplein 1",
      "postalCode": "3511 ED",
      "city": "Utrecht",
      "country": "NL",
      "addressOptions": {
        "housenumber": true,
        "geocode": true
      }
    }
  },
  "phones": {
    "mobile": {
      "phoneNumber": "0612345678",
      "country": "NL",
      "format": "INTERNATIONAL"
    }
  },
  "emails": {
    "work": {
      "emailAddress": "[email protected]"
    }
  }
}

Output

Return Type: BulkValidationOutput_v1

Field	Type	Description
`addresses`	Map of String to AddressValidationOutput_v1	The address results, keyed by the identifiers from the request.
`phones`	Map of String to PhoneValidationOutput_v1	The phone results, keyed by the identifiers from the request.
`emails`	Map of String to EmailValidationOutput_v1	The email results, keyed by the identifiers from the request.
`status`	Status_v1	The status of the request as a whole. Code `850` means the request was processed. Each item carries its own status and advice.

Each item result is the same object the single validation endpoints return:

AddressValidationOutput_v1: advice, status and a list of suggested addresses (street, housenumber, housenumberAddition, postalCode, city, state, stateCode, country, countryCode, fullAddress, latitude, longitude, geoStatus, status, advice).
PhoneValidationOutput_v1: phoneNumber (in the requested format), phoneType, countryCode, status and advice.
EmailValidationOutput_v1: complete, addressee, domain, free, disposable, status and advice.

Example Response

JSON

{
  "status": {
    "message": "BulkItem Validation Succeeded.",
    "credit": false,
    "code": "850"
  },
  "addresses": {
    "billing": {
      "status": {
        "message": "Current address is verified up to Street. Suggestion contains an improved, verified address up to Street.",
        "credit": true,
        "code": "533"
      },
      "advice": "GREEN",
      "addresses": [
        {
          "street": "Stationsplein",
          "housenumber": "1",
          "housenumberAddition": null,
          "postalCode": "3511 ED",
          "city": "Utrecht",
          "state": "Utrecht",
          "stateCode": "Utrecht",
          "country": "Nederland",
          "countryCode": "NL",
          "fullAddress": "Stationsplein 1, 3511 ED  Utrecht",
          "latitude": "52.090268744737",
          "longitude": "5.11167580457016",
          "geoStatus": {
            "message": "Medium confidence match between the location and the geocode. The location is one of several possible geopoint matches, making the result ambiguous.",
            "credit": true,
            "code": "711"
          },
          "status": {
            "message": "Current address is verified up to Street. Suggestion contains an improved, verified address up to Street.",
            "credit": true,
            "code": "533"
          },
          "advice": "GREEN"
        }
      ]
    }
  },
  "phones": {
    "mobile": {
      "status": {
        "message": "Current phone number is correct. Suggestion contains an improved, standardised phone number.",
        "credit": true,
        "code": "102"
      },
      "phoneNumber": "+31 6 12345678",
      "phoneType": "MOBILE",
      "countryCode": "NL",
      "advice": "GREEN"
    }
  },
  "emails": {
    "work": {
      "status": {
        "message": "Email is correct, but can’t be associated with a particular person.",
        "credit": true,
        "code": "313"
      },
      "complete": "[email protected]",
      "addressee": "info",
      "domain": "plauti.com",
      "free": false,
      "disposable": false,
      "advice": "GREEN"
    }
  }
}