# Business Contact ## Get Specific Business Contact > Retrieve a specific business contact for the specified merchant using the businessContactId. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v1/BusinessContacts/{merchantNumber}/{businessContactId}":{"get":{"tags":["Business Contact"],"summary":"Get Specific Business Contact","description":"Retrieve a specific business contact for the specified merchant using the businessContactId.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"businessContactId","in":"path","description":"The unique identifier for the business contact.","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"encryptedSsn","in":"query","description":"Specifies whether to return the Social Security Number (SSN) in encrypted format. Default: false.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Returns a single business contact successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContact"}}}},"400":{"description":"Bad Request: If merchant number is null or empty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"401":{"description":"Unauthorized: User does not have the required role or access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"403":{"description":"Forbidden: The user does not have the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"404":{"description":"Not Found: BusinessContacts not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"500":{"description":"Internal Server Error: This could be due to system errors. Please contact support for assistance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}}}}}},"components":{"schemas":{"MerchantDemographics.Api.Models.BusinessContact":{"required":["contact","contactTypes","emailAddress","phoneNumbers"],"type":"object","properties":{"phoneNumbers":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContactPhone"},"description":"A collection of phone numbers."},"businessContactId":{"type":"integer","description":"Unique identifier for the business contact.","format":"int32"},"contact":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.Contact"},"ownershipAmount":{"type":"string","description":"Ownership percentage or amount associated with the contact.","nullable":true},"emailAddress":{"minLength":1,"type":"string","description":"The email address of the business contact."},"title":{"type":"string","description":"Job title or position of the business contact.","nullable":true},"contactTypes":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContactContactType"},"description":"List of contact types associated with the business contact."},"isCompassUser":{"type":"boolean","description":"Indicates whether the contact is a Compass user."},"isMerchantHomeUser":{"type":"boolean","description":"Indicates whether the contact is a Merchant Home user."},"isVirtualTerminalUser":{"type":"boolean","description":"Indicates whether the contact is a Virtual Terminal user."},"isAuthorizedToPurchase":{"type":"boolean","description":"Specifies if the contact is authorized to make purchases."}},"additionalProperties":false},"MerchantDemographics.Api.Models.BusinessContactPhone":{"required":["areaCode","phoneNumber","phoneTypeCodeID"],"type":"object","properties":{"phoneTypeCodeID":{"type":"string","description":"Specifies the particular contact type."},"areaCode":{"maxLength":3,"minLength":3,"type":"string","description":"The area code of the phone number, typically 3 digits."},"phoneNumber":{"maxLength":8,"minLength":7,"type":"string","description":"The phone number without the area code. Should be between 7 and 8 digits in length.","format":"tel"},"extension":{"type":"string","description":"The phone number extension (optional).","nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.Contact":{"required":["countryOfCitizenshipCode","firstName","lastName"],"type":"object","properties":{"countryOfCitizenshipCode":{"maximum":840,"minimum":1,"type":"string","description":"The country code for the citizenship of the contact. Must be a valid ISO code between 1 and 840."},"address":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ContactAddress"},"ssnLastFour":{"type":"string","description":"The last four digits of the contact's SSN (Social Security Number). Excluded from Swagger documentation.","nullable":true},"encryptedSSN":{"type":"string","description":"The encrypted Social Security Number (SSN) of the contact.","format":"byte","nullable":true},"ssn":{"maxLength":9,"minLength":9,"type":"string","description":"The full legal ID, such as SSN, of the contact. Strips dashes automatically.","nullable":true},"contactId":{"type":"integer","description":"The unique identifier for the contact. Excluded from Swagger documentation.","format":"int32"},"firstName":{"minLength":1,"type":"string","description":"The first name of the contact."},"lastName":{"minLength":1,"type":"string","description":"The last name of the contact."},"dateOfBirth":{"type":"string","description":"The date of birth of the contact.","nullable":true},"dateOfBirthString":{"type":"string","description":"The date of birth in \"MMddyyyy\" format","nullable":true,"readOnly":true}},"additionalProperties":false,"description":"Contains all details of the business contact."},"MerchantDemographics.Api.Models.ContactAddress":{"required":["city","countryCode","line1","stateCode","zip"],"type":"object","properties":{"line1":{"minLength":1,"type":"string","description":"The first line of the address (Example, street address, P.O. box)."},"line2":{"type":"string","description":"The second line of the address (optional).","nullable":true},"line3":{"type":"string","description":"The third line of the address (optional).","nullable":true},"city":{"minLength":1,"type":"string","description":"The city or locality of the address."},"countryCode":{"maximum":840,"minimum":1,"type":"string","description":"The country code for the address. Typically a numeric code for the country."},"stateCode":{"maxLength":10,"minLength":2,"type":"string","description":"The state or region code. Typically a 2-letter code representing the state."},"zip":{"minLength":1,"type":"string","description":"The postal code (zip code) of the address."}},"additionalProperties":false,"description":"Address details of the contact."},"MerchantDemographics.Api.Models.BusinessContactContactType":{"type":"object","properties":{"businessContactContactTypeID":{"type":"integer","description":"The unique identifier for the BusinessContactContactType entity.","format":"int32"},"businessContactID":{"type":"integer","description":"The unique identifier for the associated business contact.","format":"int32"},"contactTypeID":{"type":"integer","description":"The unique identifier for the contact type associated with the business contact.","format":"int32"}},"additionalProperties":false},"MerchantDemographics.Api.Models.ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BoardingError"},"nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.BoardingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Describes the error and provide detailed information on what went wrong during the request processing.","nullable":true},"resultCode":{"type":"integer","description":"Code associated with the error and helps to categorize the error type or severity. (It can be any error code 400/401/501, etc depending upon its type)","format":"int32"},"timeStamp":{"type":"string","description":"DateTime in ISO 8601 format. It is read-only and automatically set to the current date and time.","format":"date-time","readOnly":true},"fieldPath":{"type":"array","items":{"type":"string"},"description":"Field path(s) where the error occurred in a data structure. It can contains any field.","nullable":true}},"additionalProperties":false}}}} ``` ## Update Business Contact > Update an existing business contact for the specified merchant. > \ > > \ > Note: The request requires the merchantNumber and businessContactId as route parameters, and the updated business contact details in the request body. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v1/BusinessContacts/{merchantNumber}/{businessContactId}":{"put":{"tags":["Business Contact"],"summary":"Update Business Contact","description":"Update an existing business contact for the specified merchant.\r\n \r\nNote: The request requires the merchantNumber and businessContactId as route parameters, and the updated business contact details in the request body.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"businessContactId","in":"path","description":"The unique identifier for the business contact.","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"encryptedSsn","in":"query","description":"Specifies whether to return the Social Security Number (SSN) in encrypted format. Default: false.","schema":{"type":"boolean","default":false}}],"requestBody":{"description":"BusinessContact model contains details to update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContact"}}},"required":true},"responses":{"200":{"description":"Updates a business contact successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContact"}}}},"202":{"description":"Accepted: Request change was accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedChange.Client.Models.StagedChangeResponse"}}}},"400":{"description":"Bad Request: If merchantNumber is null or empty, or data is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Validation.SerializableValidationResult"}}}},"401":{"description":"Unauthorized: User does not have the required role or access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"403":{"description":"Forbidden: The user does not have the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"404":{"description":"Not Found: If contact is not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"409":{"description":"Conflict: Request change was rejected because there is another one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"500":{"description":"Internal Server Error: This could be due to system errors. Please contact support for assistance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}}}}}},"components":{"schemas":{"MerchantDemographics.Api.Models.BusinessContact":{"required":["contact","contactTypes","emailAddress","phoneNumbers"],"type":"object","properties":{"phoneNumbers":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContactPhone"},"description":"A collection of phone numbers."},"businessContactId":{"type":"integer","description":"Unique identifier for the business contact.","format":"int32"},"contact":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.Contact"},"ownershipAmount":{"type":"string","description":"Ownership percentage or amount associated with the contact.","nullable":true},"emailAddress":{"minLength":1,"type":"string","description":"The email address of the business contact."},"title":{"type":"string","description":"Job title or position of the business contact.","nullable":true},"contactTypes":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContactContactType"},"description":"List of contact types associated with the business contact."},"isCompassUser":{"type":"boolean","description":"Indicates whether the contact is a Compass user."},"isMerchantHomeUser":{"type":"boolean","description":"Indicates whether the contact is a Merchant Home user."},"isVirtualTerminalUser":{"type":"boolean","description":"Indicates whether the contact is a Virtual Terminal user."},"isAuthorizedToPurchase":{"type":"boolean","description":"Specifies if the contact is authorized to make purchases."}},"additionalProperties":false},"MerchantDemographics.Api.Models.BusinessContactPhone":{"required":["areaCode","phoneNumber","phoneTypeCodeID"],"type":"object","properties":{"phoneTypeCodeID":{"type":"string","description":"Specifies the particular contact type."},"areaCode":{"maxLength":3,"minLength":3,"type":"string","description":"The area code of the phone number, typically 3 digits."},"phoneNumber":{"maxLength":8,"minLength":7,"type":"string","description":"The phone number without the area code. Should be between 7 and 8 digits in length.","format":"tel"},"extension":{"type":"string","description":"The phone number extension (optional).","nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.Contact":{"required":["countryOfCitizenshipCode","firstName","lastName"],"type":"object","properties":{"countryOfCitizenshipCode":{"maximum":840,"minimum":1,"type":"string","description":"The country code for the citizenship of the contact. Must be a valid ISO code between 1 and 840."},"address":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ContactAddress"},"ssnLastFour":{"type":"string","description":"The last four digits of the contact's SSN (Social Security Number). Excluded from Swagger documentation.","nullable":true},"encryptedSSN":{"type":"string","description":"The encrypted Social Security Number (SSN) of the contact.","format":"byte","nullable":true},"ssn":{"maxLength":9,"minLength":9,"type":"string","description":"The full legal ID, such as SSN, of the contact. Strips dashes automatically.","nullable":true},"contactId":{"type":"integer","description":"The unique identifier for the contact. Excluded from Swagger documentation.","format":"int32"},"firstName":{"minLength":1,"type":"string","description":"The first name of the contact."},"lastName":{"minLength":1,"type":"string","description":"The last name of the contact."},"dateOfBirth":{"type":"string","description":"The date of birth of the contact.","nullable":true},"dateOfBirthString":{"type":"string","description":"The date of birth in \"MMddyyyy\" format","nullable":true,"readOnly":true}},"additionalProperties":false,"description":"Contains all details of the business contact."},"MerchantDemographics.Api.Models.ContactAddress":{"required":["city","countryCode","line1","stateCode","zip"],"type":"object","properties":{"line1":{"minLength":1,"type":"string","description":"The first line of the address (Example, street address, P.O. box)."},"line2":{"type":"string","description":"The second line of the address (optional).","nullable":true},"line3":{"type":"string","description":"The third line of the address (optional).","nullable":true},"city":{"minLength":1,"type":"string","description":"The city or locality of the address."},"countryCode":{"maximum":840,"minimum":1,"type":"string","description":"The country code for the address. Typically a numeric code for the country."},"stateCode":{"maxLength":10,"minLength":2,"type":"string","description":"The state or region code. Typically a 2-letter code representing the state."},"zip":{"minLength":1,"type":"string","description":"The postal code (zip code) of the address."}},"additionalProperties":false,"description":"Address details of the contact."},"MerchantDemographics.Api.Models.BusinessContactContactType":{"type":"object","properties":{"businessContactContactTypeID":{"type":"integer","description":"The unique identifier for the BusinessContactContactType entity.","format":"int32"},"businessContactID":{"type":"integer","description":"The unique identifier for the associated business contact.","format":"int32"},"contactTypeID":{"type":"integer","description":"The unique identifier for the contact type associated with the business contact.","format":"int32"}},"additionalProperties":false},"StagedChange.Client.Models.StagedChangeResponse":{"type":"object","properties":{"uniqueIdentifier":{"type":"string","nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Validation.SerializableValidationResult":{"type":"object","properties":{"errorMessagesByMemberName":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"nullable":true},"description":"A dictionary of error messages categorized by member name.","nullable":true,"readOnly":true},"generalErrorMessages":{"type":"array","items":{"type":"string"},"description":"A list of general error messages not associated with any specific member.","nullable":true,"readOnly":true},"success":{"type":"boolean","description":"Indicates whether the validation was successful.","readOnly":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BoardingError"},"nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.BoardingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Describes the error and provide detailed information on what went wrong during the request processing.","nullable":true},"resultCode":{"type":"integer","description":"Code associated with the error and helps to categorize the error type or severity. (It can be any error code 400/401/501, etc depending upon its type)","format":"int32"},"timeStamp":{"type":"string","description":"DateTime in ISO 8601 format. It is read-only and automatically set to the current date and time.","format":"date-time","readOnly":true},"fieldPath":{"type":"array","items":{"type":"string"},"description":"Field path(s) where the error occurred in a data structure. It can contains any field.","nullable":true}},"additionalProperties":false}}}} ``` ## Delete Business Contact > Delete the business contact for the specified merchant using the provided businessContactId. > \\ > > \ > Note: > \ > The deletion occurs only if the merchant account is not locked and at least one business contact remains. > \ > An audit entry is queued for successful deletions; otherwise, the request may be staged for later processing. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v1/BusinessContacts/{merchantNumber}/{businessContactId}":{"delete":{"tags":["Business Contact"],"summary":"Delete Business Contact","description":"Delete the business contact for the specified merchant using the provided businessContactId.\r\n\r\nNote:\r\nThe deletion occurs only if the merchant account is not locked and at least one business contact remains.\r\nAn audit entry is queued for successful deletions; otherwise, the request may be staged for later processing.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"businessContactId","in":"path","description":"The unique identifier for the business contact.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Deletes a business contact successfully."},"202":{"description":"Accepted: Request change was accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedChange.Client.Models.StagedChangeResponse"}}}},"400":{"description":"Bad Request: If MerchantNumber is null or it's the only contact of the merchant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"401":{"description":"Unauthorized: User does not have the required role or access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"403":{"description":"Forbidden: The user does not have the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"404":{"description":"Not Found: If contact is not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"409":{"description":"Conflict: Request change was rejected because there is another one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"500":{"description":"Internal Server Error: This could be due to system errors. Please contact support for assistance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}}}}}},"components":{"schemas":{"StagedChange.Client.Models.StagedChangeResponse":{"type":"object","properties":{"uniqueIdentifier":{"type":"string","nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BoardingError"},"nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.BoardingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Describes the error and provide detailed information on what went wrong during the request processing.","nullable":true},"resultCode":{"type":"integer","description":"Code associated with the error and helps to categorize the error type or severity. (It can be any error code 400/401/501, etc depending upon its type)","format":"int32"},"timeStamp":{"type":"string","description":"DateTime in ISO 8601 format. It is read-only and automatically set to the current date and time.","format":"date-time","readOnly":true},"fieldPath":{"type":"array","items":{"type":"string"},"description":"Field path(s) where the error occurred in a data structure. It can contains any field.","nullable":true}},"additionalProperties":false}}}} ``` ## Get Business Contacts > Retrieve all business contacts associated with the merchant. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v1/BusinessContacts/{merchantNumber}":{"get":{"tags":["Business Contact"],"summary":"Get Business Contacts","description":"Retrieve all business contacts associated with the merchant.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"encryptedSsn","in":"query","description":"Specifies whether to return the Social Security Number (SSN) in encrypted format. Default: false.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Returns a list of business contacts successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContactCollection"}}}},"400":{"description":"If merchantNumber is null or empty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"404":{"description":"If no contacts returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"500":{"description":"Error occurred retrieving data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}}}}}},"components":{"schemas":{"MerchantDemographics.Api.Models.BusinessContactCollection":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContact"},"nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.BusinessContact":{"required":["contact","contactTypes","emailAddress","phoneNumbers"],"type":"object","properties":{"phoneNumbers":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContactPhone"},"description":"A collection of phone numbers."},"businessContactId":{"type":"integer","description":"Unique identifier for the business contact.","format":"int32"},"contact":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.Contact"},"ownershipAmount":{"type":"string","description":"Ownership percentage or amount associated with the contact.","nullable":true},"emailAddress":{"minLength":1,"type":"string","description":"The email address of the business contact."},"title":{"type":"string","description":"Job title or position of the business contact.","nullable":true},"contactTypes":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContactContactType"},"description":"List of contact types associated with the business contact."},"isCompassUser":{"type":"boolean","description":"Indicates whether the contact is a Compass user."},"isMerchantHomeUser":{"type":"boolean","description":"Indicates whether the contact is a Merchant Home user."},"isVirtualTerminalUser":{"type":"boolean","description":"Indicates whether the contact is a Virtual Terminal user."},"isAuthorizedToPurchase":{"type":"boolean","description":"Specifies if the contact is authorized to make purchases."}},"additionalProperties":false},"MerchantDemographics.Api.Models.BusinessContactPhone":{"required":["areaCode","phoneNumber","phoneTypeCodeID"],"type":"object","properties":{"phoneTypeCodeID":{"type":"string","description":"Specifies the particular contact type."},"areaCode":{"maxLength":3,"minLength":3,"type":"string","description":"The area code of the phone number, typically 3 digits."},"phoneNumber":{"maxLength":8,"minLength":7,"type":"string","description":"The phone number without the area code. Should be between 7 and 8 digits in length.","format":"tel"},"extension":{"type":"string","description":"The phone number extension (optional).","nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.Contact":{"required":["countryOfCitizenshipCode","firstName","lastName"],"type":"object","properties":{"countryOfCitizenshipCode":{"maximum":840,"minimum":1,"type":"string","description":"The country code for the citizenship of the contact. Must be a valid ISO code between 1 and 840."},"address":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ContactAddress"},"ssnLastFour":{"type":"string","description":"The last four digits of the contact's SSN (Social Security Number). Excluded from Swagger documentation.","nullable":true},"encryptedSSN":{"type":"string","description":"The encrypted Social Security Number (SSN) of the contact.","format":"byte","nullable":true},"ssn":{"maxLength":9,"minLength":9,"type":"string","description":"The full legal ID, such as SSN, of the contact. Strips dashes automatically.","nullable":true},"contactId":{"type":"integer","description":"The unique identifier for the contact. Excluded from Swagger documentation.","format":"int32"},"firstName":{"minLength":1,"type":"string","description":"The first name of the contact."},"lastName":{"minLength":1,"type":"string","description":"The last name of the contact."},"dateOfBirth":{"type":"string","description":"The date of birth of the contact.","nullable":true},"dateOfBirthString":{"type":"string","description":"The date of birth in \"MMddyyyy\" format","nullable":true,"readOnly":true}},"additionalProperties":false,"description":"Contains all details of the business contact."},"MerchantDemographics.Api.Models.ContactAddress":{"required":["city","countryCode","line1","stateCode","zip"],"type":"object","properties":{"line1":{"minLength":1,"type":"string","description":"The first line of the address (Example, street address, P.O. box)."},"line2":{"type":"string","description":"The second line of the address (optional).","nullable":true},"line3":{"type":"string","description":"The third line of the address (optional).","nullable":true},"city":{"minLength":1,"type":"string","description":"The city or locality of the address."},"countryCode":{"maximum":840,"minimum":1,"type":"string","description":"The country code for the address. Typically a numeric code for the country."},"stateCode":{"maxLength":10,"minLength":2,"type":"string","description":"The state or region code. Typically a 2-letter code representing the state."},"zip":{"minLength":1,"type":"string","description":"The postal code (zip code) of the address."}},"additionalProperties":false,"description":"Address details of the contact."},"MerchantDemographics.Api.Models.BusinessContactContactType":{"type":"object","properties":{"businessContactContactTypeID":{"type":"integer","description":"The unique identifier for the BusinessContactContactType entity.","format":"int32"},"businessContactID":{"type":"integer","description":"The unique identifier for the associated business contact.","format":"int32"},"contactTypeID":{"type":"integer","description":"The unique identifier for the contact type associated with the business contact.","format":"int32"}},"additionalProperties":false},"MerchantDemographics.Api.Models.ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BoardingError"},"nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.BoardingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Describes the error and provide detailed information on what went wrong during the request processing.","nullable":true},"resultCode":{"type":"integer","description":"Code associated with the error and helps to categorize the error type or severity. (It can be any error code 400/401/501, etc depending upon its type)","format":"int32"},"timeStamp":{"type":"string","description":"DateTime in ISO 8601 format. It is read-only and automatically set to the current date and time.","format":"date-time","readOnly":true},"fieldPath":{"type":"array","items":{"type":"string"},"description":"Field path(s) where the error occurred in a data structure. It can contains any field.","nullable":true}},"additionalProperties":false}}}} ``` ## Create Business Contact > Create a business contact for the specified merchant. > \ > > \ > Note: > \ > The created business contact can be used for further processing within the system. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v1/BusinessContacts/{merchantNumber}":{"post":{"tags":["Business Contact"],"summary":"Create Business Contact","description":"Create a business contact for the specified merchant.\r\n \r\nNote: \r\nThe created business contact can be used for further processing within the system.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"encryptedSsn","in":"query","description":"Specifies whether to return the Social Security Number (SSN) in encrypted format. Default: false.","schema":{"type":"boolean","default":false}}],"requestBody":{"description":"BusinessContact model conatins details to create business contact.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContact"}}},"required":true},"responses":{"201":{"description":"Creates a business contact successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContact"}}}},"202":{"description":"Accepted: Request change was accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedChange.Client.Models.StagedChangeResponse"}}}},"400":{"description":"Bad Request: If merchantNumber is null or empty, or data is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"401":{"description":"Unauthorized: User does not have the required role or access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"403":{"description":"Forbidden: The user does not have the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"404":{"description":"Not Found: If exception is thrown during creation or merchant contact not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"409":{"description":"Conflict: Request change was rejected because there is another one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"500":{"description":"Internal Server Error: This could be due to system errors. Please contact support for assistance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}}}}}},"components":{"schemas":{"MerchantDemographics.Api.Models.BusinessContact":{"required":["contact","contactTypes","emailAddress","phoneNumbers"],"type":"object","properties":{"phoneNumbers":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContactPhone"},"description":"A collection of phone numbers."},"businessContactId":{"type":"integer","description":"Unique identifier for the business contact.","format":"int32"},"contact":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.Contact"},"ownershipAmount":{"type":"string","description":"Ownership percentage or amount associated with the contact.","nullable":true},"emailAddress":{"minLength":1,"type":"string","description":"The email address of the business contact."},"title":{"type":"string","description":"Job title or position of the business contact.","nullable":true},"contactTypes":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BusinessContactContactType"},"description":"List of contact types associated with the business contact."},"isCompassUser":{"type":"boolean","description":"Indicates whether the contact is a Compass user."},"isMerchantHomeUser":{"type":"boolean","description":"Indicates whether the contact is a Merchant Home user."},"isVirtualTerminalUser":{"type":"boolean","description":"Indicates whether the contact is a Virtual Terminal user."},"isAuthorizedToPurchase":{"type":"boolean","description":"Specifies if the contact is authorized to make purchases."}},"additionalProperties":false},"MerchantDemographics.Api.Models.BusinessContactPhone":{"required":["areaCode","phoneNumber","phoneTypeCodeID"],"type":"object","properties":{"phoneTypeCodeID":{"type":"string","description":"Specifies the particular contact type."},"areaCode":{"maxLength":3,"minLength":3,"type":"string","description":"The area code of the phone number, typically 3 digits."},"phoneNumber":{"maxLength":8,"minLength":7,"type":"string","description":"The phone number without the area code. Should be between 7 and 8 digits in length.","format":"tel"},"extension":{"type":"string","description":"The phone number extension (optional).","nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.Contact":{"required":["countryOfCitizenshipCode","firstName","lastName"],"type":"object","properties":{"countryOfCitizenshipCode":{"maximum":840,"minimum":1,"type":"string","description":"The country code for the citizenship of the contact. Must be a valid ISO code between 1 and 840."},"address":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ContactAddress"},"ssnLastFour":{"type":"string","description":"The last four digits of the contact's SSN (Social Security Number). Excluded from Swagger documentation.","nullable":true},"encryptedSSN":{"type":"string","description":"The encrypted Social Security Number (SSN) of the contact.","format":"byte","nullable":true},"ssn":{"maxLength":9,"minLength":9,"type":"string","description":"The full legal ID, such as SSN, of the contact. Strips dashes automatically.","nullable":true},"contactId":{"type":"integer","description":"The unique identifier for the contact. Excluded from Swagger documentation.","format":"int32"},"firstName":{"minLength":1,"type":"string","description":"The first name of the contact."},"lastName":{"minLength":1,"type":"string","description":"The last name of the contact."},"dateOfBirth":{"type":"string","description":"The date of birth of the contact.","nullable":true},"dateOfBirthString":{"type":"string","description":"The date of birth in \"MMddyyyy\" format","nullable":true,"readOnly":true}},"additionalProperties":false,"description":"Contains all details of the business contact."},"MerchantDemographics.Api.Models.ContactAddress":{"required":["city","countryCode","line1","stateCode","zip"],"type":"object","properties":{"line1":{"minLength":1,"type":"string","description":"The first line of the address (Example, street address, P.O. box)."},"line2":{"type":"string","description":"The second line of the address (optional).","nullable":true},"line3":{"type":"string","description":"The third line of the address (optional).","nullable":true},"city":{"minLength":1,"type":"string","description":"The city or locality of the address."},"countryCode":{"maximum":840,"minimum":1,"type":"string","description":"The country code for the address. Typically a numeric code for the country."},"stateCode":{"maxLength":10,"minLength":2,"type":"string","description":"The state or region code. Typically a 2-letter code representing the state."},"zip":{"minLength":1,"type":"string","description":"The postal code (zip code) of the address."}},"additionalProperties":false,"description":"Address details of the contact."},"MerchantDemographics.Api.Models.BusinessContactContactType":{"type":"object","properties":{"businessContactContactTypeID":{"type":"integer","description":"The unique identifier for the BusinessContactContactType entity.","format":"int32"},"businessContactID":{"type":"integer","description":"The unique identifier for the associated business contact.","format":"int32"},"contactTypeID":{"type":"integer","description":"The unique identifier for the contact type associated with the business contact.","format":"int32"}},"additionalProperties":false},"StagedChange.Client.Models.StagedChangeResponse":{"type":"object","properties":{"uniqueIdentifier":{"type":"string","nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BoardingError"},"nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.BoardingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Describes the error and provide detailed information on what went wrong during the request processing.","nullable":true},"resultCode":{"type":"integer","description":"Code associated with the error and helps to categorize the error type or severity. (It can be any error code 400/401/501, etc depending upon its type)","format":"int32"},"timeStamp":{"type":"string","description":"DateTime in ISO 8601 format. It is read-only and automatically set to the current date and time.","format":"date-time","readOnly":true},"fieldPath":{"type":"array","items":{"type":"string"},"description":"Field path(s) where the error occurred in a data structure. It can contains any field.","nullable":true}},"additionalProperties":false}}}} ``` ## Get Ownership Disclosure > Retrieve the Beneficial Owner Disclosure for the specified merchant. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v1/BusinessContacts/{merchantNumber}/beneficialowneragreement":{"get":{"tags":["Business Contact"],"summary":"Get Ownership Disclosure","description":"Retrieve the Beneficial Owner Disclosure for the specified merchant.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns a business contact successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BeneficialOwnerDisclosure"}}}},"400":{"description":"Bad Request: The request made by the user is invalid and cannot be processed (If MerchantNumber is null or Empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"401":{"description":"Unauthorized: User does not have the required role or access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"403":{"description":"Forbidden: The user does not have the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"404":{"description":"Not Found: If resource not found exception is thrown during creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"500":{"description":"Internal Server Error: This could be due to system errors. Please contact support for assistance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}}}}}},"components":{"schemas":{"MerchantDemographics.Api.Models.BeneficialOwnerDisclosure":{"type":"object","properties":{"allPersonsWithOverTwentyFivePercentOwnershipHaveBeenAdded":{"type":"boolean","description":"Indicates whether all persons with more than 25% ownership have been added to the disclosure."}},"additionalProperties":false},"MerchantDemographics.Api.Models.ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BoardingError"},"nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.BoardingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Describes the error and provide detailed information on what went wrong during the request processing.","nullable":true},"resultCode":{"type":"integer","description":"Code associated with the error and helps to categorize the error type or severity. (It can be any error code 400/401/501, etc depending upon its type)","format":"int32"},"timeStamp":{"type":"string","description":"DateTime in ISO 8601 format. It is read-only and automatically set to the current date and time.","format":"date-time","readOnly":true},"fieldPath":{"type":"array","items":{"type":"string"},"description":"Field path(s) where the error occurred in a data structure. It can contains any field.","nullable":true}},"additionalProperties":false}}}} ``` ## Create Ownership Disclosure > Create a new Beneficial Owner Disclosure for the specified merchant. > \ > > \ > Note: The request requires a valid BeneficialOwnerDisclosure object in the request body. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v1/BusinessContacts/{merchantNumber}/beneficialowneragreement":{"post":{"tags":["Business Contact"],"summary":"Create Ownership Disclosure","description":"Create a new Beneficial Owner Disclosure for the specified merchant.\r\n \r\nNote: The request requires a valid BeneficialOwnerDisclosure object in the request body.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BeneficialOwnerDisclosure"}}},"required":true},"responses":{"200":{"description":"Business contact created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BeneficialOwnerDisclosure"}}}},"400":{"description":"Bad Request: The request made by the user is invalid and cannot be processed (If input is null or Empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"401":{"description":"Unauthorized: User does not have the required role or access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"403":{"description":"Forbidden: The user does not have the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"404":{"description":"Not Found: If resource not found exception is thrown during creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"500":{"description":"Internal Server Error: This could be due to system errors. Please contact support for assistance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}}}}}},"components":{"schemas":{"MerchantDemographics.Api.Models.BeneficialOwnerDisclosure":{"type":"object","properties":{"allPersonsWithOverTwentyFivePercentOwnershipHaveBeenAdded":{"type":"boolean","description":"Indicates whether all persons with more than 25% ownership have been added to the disclosure."}},"additionalProperties":false},"MerchantDemographics.Api.Models.ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BoardingError"},"nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.BoardingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Describes the error and provide detailed information on what went wrong during the request processing.","nullable":true},"resultCode":{"type":"integer","description":"Code associated with the error and helps to categorize the error type or severity. (It can be any error code 400/401/501, etc depending upon its type)","format":"int32"},"timeStamp":{"type":"string","description":"DateTime in ISO 8601 format. It is read-only and automatically set to the current date and time.","format":"date-time","readOnly":true},"fieldPath":{"type":"array","items":{"type":"string"},"description":"Field path(s) where the error occurred in a data structure. It can contains any field.","nullable":true}},"additionalProperties":false}}}} ``` ## Update Ownership Disclosure > Update an existing Beneficial Owner Disclosure for the specified merchant. > \ > > \ > Note: Pass the updated BeneficialOwnerDisclosure object in request body. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v1/BusinessContacts/{merchantNumber}/beneficialowneragreement":{"put":{"tags":["Business Contact"],"summary":"Update Ownership Disclosure","description":"Update an existing Beneficial Owner Disclosure for the specified merchant.\r\n \r\nNote: Pass the updated BeneficialOwnerDisclosure object in request body.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BeneficialOwnerDisclosure"}}},"required":true},"responses":{"200":{"description":"Updates a business contact successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BeneficialOwnerDisclosure"}}}},"400":{"description":"Bad Request: The request made by the user is invalid and cannot be processed (If input is null or Empty).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"401":{"description":"Unauthorized: User does not have the required role or access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"403":{"description":"Forbidden: The user does not have the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"404":{"description":"Not Found: If resource not found exception is thrown during creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}},"500":{"description":"Internal Server Error: This could be due to system errors. Please contact support for assistance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.ErrorResults"}}}}}}}},"components":{"schemas":{"MerchantDemographics.Api.Models.BeneficialOwnerDisclosure":{"type":"object","properties":{"allPersonsWithOverTwentyFivePercentOwnershipHaveBeenAdded":{"type":"boolean","description":"Indicates whether all persons with more than 25% ownership have been added to the disclosure."}},"additionalProperties":false},"MerchantDemographics.Api.Models.ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.BoardingError"},"nullable":true}},"additionalProperties":false},"MerchantDemographics.Api.Models.BoardingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Describes the error and provide detailed information on what went wrong during the request processing.","nullable":true},"resultCode":{"type":"integer","description":"Code associated with the error and helps to categorize the error type or severity. (It can be any error code 400/401/501, etc depending upon its type)","format":"int32"},"timeStamp":{"type":"string","description":"DateTime in ISO 8601 format. It is read-only and automatically set to the current date and time.","format":"date-time","readOnly":true},"fieldPath":{"type":"array","items":{"type":"string"},"description":"Field path(s) where the error occurred in a data structure. It can contains any field.","nullable":true}},"additionalProperties":false}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.xplorpay.com/api-reference/api/merchant-onboarding/onboard-merchant/merchant-demographics/business-contact-1.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.