Apex EDI Vendor Portal

Apex EDI API V3 Documentation

Enrollment API Reference

The Apex Enrollment API v3 allows Apex partners to enroll billing providers with payers. Information about the billing provider is submitted to Apex’s enrollment system to begin the enrollment process.

The enrollment API is used in the following manner. When a new billing provider is created in the partner’s system, the partner sends certain information to Apex to initiate the enrollment process. Apex verifies that:

  • The request was valid,
  • The billing provider was added to the enrollment system,
  • The billing provider was already added for enrollment,
  • A message will be returned if there was an exception thrown when attempting to add the provider to the system.

Please note the following:

  • Apex tests API requests for validity.
  • When a request is rejected by Apex as invalid, it must be corrected before it is resubmitted. If an invalid request is rejected and resubmitted again unchanged, it will simply be rejected again.
  • While submitting an additional request with the same information after a successful submission should be avoided, it is not an error. The response will indicate that the billing provider already exists.
  • If an error is returned by the enrollment system, then the request must be corrected before it is resubmitted.
  • The Version field at the top level of the request is required, and the value must be 1. This value is for future use. If the API is revised in a backwards-incompatible way, then a new version of the API will be created. Requests that conform to version 1 will continue to work during a transition period, and the new version number will be required for the new features to be accessible. For now, if any version number other than 1 is supplied, or if the version number is missing, then the requests will be rejected as invalid.

Host Names

See the Host Names section of the claims documentation.

Processing of Providers by Apex

The SubmitEnrollments API described in this section is only used for submitting enrollment requests for Apex. Apex does not otherwise process or retain any information submitted to this API. For partners using version 4 of the partner integration API (PIv4) for submitting claims, providers are created in the Apex system as a side effect of submitting claims. The SubmitEnrollments API does not result in any provider being added to the Apex system.

Partners using version 3 of the Apex API may use the SubmitEnrollments API described here to submit enrollment requests to Apex. Such partners should contact Apex to determine how providers should be submitted to the Apex system.

Return Values and Errors

The following fields in returned EnrollmentResult objects are no longer used and can be ignored

  • HttpReturnCode
  • SiteCreated
  • MedicalGroupCreated
  • PracticeCreated
  • JsonResponse

The response to a submission consists of a hierarchy of responses with two levels. The upper level corresponds to the overall request, while at the lower level there are responses for each individual provider from the list contained in the overall request. It will always be present. If the overall response code is in the 200 (success) range, then the body of the response will consist of a JSON object with a single field, EnrollmentResults, which consists of an array of individual results.

If the overall response code is in the 400 or 500 range, then an error has occurred and the body of the response contains a description of the error. In this case, the entire overall request, potentially consisting of multiple individual requests, has failed, and there will be no individual responses.

If the response code is in the 200 range, then the overall request was processed and there should be an EnrollmentResult in the EnrollmentResults array for each individual request. A submission can be assumed to have completed successfully if the Message and Exception fields show no errors.

A 400-level response means that there was an error in the overall request and therefore the entire request with all the individual requests has failed. The error must be corrected before the submission can be retried. In this case, there was no attempt to send any individual requests to the enrollment system, and all requests have failed.

A 500-level response means that there was some internal error within the Apex system, and that the entire request should be resubmitted later. In this case no error has been detected in the request, and it can be submitted again later unchanged.

Also see the Return Values and Errors section of the claims documentation for a description of certain errors that may occur that are common to both claims submission and enrollment submission.

When to Submit a Request

A new enrollment request must be submitted for each new provider added for a client. The request must include the tax ID and the billing NPI of the provider. Once the enrollment request has been successfully submitted, the client will be contacted and they will be assisted to get all of their providers enrolled with all associated payers until they are successfully submitting claims, and receiving ERAs.

Please note that the address supplied in the request (PO boxes not allowed) must match the address associated with the NPI on file with payers; otherwise, the request may be rejected by the payer.

SubmitEnrollments

/api/v3/enrollment/submit?vendorSiteId=<vendorSiteId>

where vendorSiteId is the assigned Vendor Site ID

The body of the HTTP request is a JSON object with the required field Version. The required field Enrollments is an array of one or more individual enrollment requests. The HTTP request verb must be POST.

Unless otherwise noted, there is no restriction on the characters that may appear in strings.

Enrollment request details

The enrollment request consists of a version number and an array of individual request objects.

  • Version. Integer. Required. Must be 1 at this time to indicate the first version of the API.
  • Enrollments. Array. Required. The array of individual enrollment objects. There must be at least one member of the array.

The individual request objects have the following fields:

  • RequestId. String. Required. An identifier to distinguish the individual request objects in the overall request from one another. The ID is copied to the individual response object so that the response can be matched to the request.
  • SiteId. String. Deprecated.
  • Npi. String. Required. The billing provider National Provider ID. Must be exactly 10 decimal digits.
  • NpiType. String. Required. Must be one of Unknown, Individual, or Organization.
  • Tin. String. Required. The tax ID number of the billing provider. Must be exactly 9 decimal digits.
  • PracticeName. String. Situational. Required if NpiType is Organization. Must be between 1 and 60 characters in length.
  • DbaName. String. Optional. Alternative billing name. Maximum length is 60 characters.
  • ProviderTitle. String. Optional. Maximum length is 60 characters.
  • ProviderLastName. String. Situational. Required if NpiType is Individual. If set, must be between 1 and 60 characters in length.
  • ProviderFirstName. String. Situational. Required if NpiType is Individual. If set, must be between 1 and 35 characters in length.
  • ProviderMiddleName. Optional. Maximum length is 25 characters.
  • Address1. String. Required. Must be between 1 and 55 characters in length.
  • Address2. String. Optional. Maximum length is 55 characters
  • City. String. Required. Must be between 2 and 30 characters in length.
  • State. String. Required. Must be exactly 2 characters in length.
  • Zip. String. Required. The U.S. ZIP code. Must be exactly 5 characters in length.
  • ZipExtension. String. Optional. The four extra characters of the ZIP+4 ZIP code. If present, must be exactly 4 characters in length.
  • PreviousClearingHouse. String. Optional. Maximum length is 250 characters.
  • EnrollmentContactLastName. String. Optional. Maximum length is 60 characters.
  • EnrollmentContactFirstName. String. Optional. Maximum length is 35 characters.
  • EnrollmentContactMiddleName. String. Optional. Maximum length is 25 characters.
  • EnrollmentContactEmail. String. Optional. Maximum length is 256 characters.
  • EnrollmentContactPhoneNumber. String. Optional. Maximum length is 10 characters
  • PrimaryContactLastName. String. Required. Must be between 1 and 60 characters in length.
  • PrimaryContactFirstName. String. Required. Must be between 1 and 35 characters in length.
  • PrimaryContactMiddleName. String. Optional. Maximum length is 25 characters.
  • PrimaryContactEmail. String. Required. Must be a valid email address between 1 and 256 characters in length.
  • PrimaryContactPhoneNumber. String. Required. Must be exactly 10 decimal digits. The first digit must not be zero or one.

Sample request

The example is for two requests for the same client. The requests differ only in the NPI.

{
	"Version": 1,
	"Enrollments": [
		{
			"RequestId": "0",
			"Npi": "1111111112",
			"NpiType": 2,
			"Tin": "123456789",
			"PracticeName": "Smith Medical Clinic",
			"DbaName": "Advanced Clinic Care",
			"ProviderLastName": "Smith",
			"ProviderFirstName": "Jane",
			"ProviderMiddleName": "R",
			"Address1": "951 E 1270 South",
			"City": "Provo",
			"State": "UT",
			"Zip": "84606",
			"PreviousClearingHouse": "Amalgamated Clearinghouse",
			"PrimaryContactLastName": "Valdez",
			"PrimaryContactFirstName": "Juan",
			"PrimaryContactEmail": "jvaldez@example.com",
			"PrimaryContactPhoneNumber": "8015555555"
		},
		{
			"RequestId": "1",
			"Npi": "1111111120",
			"NpiType": 2,
			"Tin": "123456789",
			"PracticeName": "Smith Medical Clinic",
			"DbaName": "Advanced Clinic Care",
			"ProviderLastName": "Smith",
			"ProviderFirstName": "Jane",
			"ProviderMiddleName": "R",
			"Address1": "951 E 1270 South",
			"City": "Provo",
			"State": "UT",
			"Zip": "84606",
			"PreviousClearingHouse": "Amalgamated Clearinghouse",
			"EnrollmentContactLastName": "Jones",
			"EnrollmentContactFirstName": "John",
			"EnrollmentContactMiddleName": "Q",
			"EnrollmentContactEmail": "jjones@example.com",
			"EnrollmentContactPhoneNumber": "8015555555",
			"PrimaryContactLastName": "Valdez",
			"PrimaryContactFirstName": "Juan",
			"PrimaryContactEmail": "jvaldez@example.com",
			"PrimaryContactPhoneNumber": "8015555555"
		},
	]
}

How to match a response to a request

The overall request consists of an array of individual request objects. The value of RequestId must is a string. Within a single array of individual requests, each value of RequestId must be unique. The value of RequestId in each individual response is simply copied from the corresponding individual request object.

Values of RequestId may be reused across overall request arrays. For example, it is acceptable to simply number the individual requests "0", "1", "2", "3", …, and so forth on each call to the API.

How to interpret the response

  • If the HTTP return code is in the 200 range in the HTTP header of the response for the overall request itself, and if there are no errors appearing in the Message or Exception fields, the submission was successful.
  • HTTP return code is in the 400 in the HTTP header of the response for the overall request itself (not the HttpReturnCode field of a particular response object in the body of the response). A validation error occurred. None of the individual requests in the entire array of requests were submitted for enrollment. The validation errors are returned in the body of the response. There is a message and an array of key/value pairs with details on the validation errors.
  • HTTP return code is 503. Part of the Apex enrollment service is unavailable. The request should be tried again later.
  • HTTP return code is in the 500 range, but not 503. An unanticipated error occurred. The request should be tried again later.
  • See also the section on Return Values and Errors in the Claim API reference of the documentation on various other errors than can occur, such as authentication errors, use of incorrect HTTP verb, etc.

Sample response

  • HttpStatusCode: 200 (OK)
  • Body:
    {
	EnrollmentResults: [
		{
			RequestId: "0",
			ClientId: "XYZ",
			LastName: "Johnson",
			FirstName: "Pauline",
			LineNumber: "5",
			Message "",
			Exception "",
			HttpReturnCode: null,
			SiteCreated: false,
			MedicalGroupCreated: false,
			PracticeCreated: false,
			JsonResponse: null,
		},
		{
			RequestId: "1",
			ClientId: "XYZ",
			LastName: "Petrov",
			FirstName: "Dmitri",
			LineNumber: "2",
			Message "",
			Exception "",
			HttpReturnCode: null,
			SiteCreated: false,
			MedicalGroupCreated: false,
			PracticeCreated: false,
			JsonResponse: null,
		}
	]
}