# Tax Payer ## Get taxpayer details > Retrieve taxpayer details for the merchant identified by merchantNumber. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v2/Taxpayers/{merchantNumber}":{"get":{"tags":["Tax Payer"],"summary":"Get taxpayer details","description":"Retrieve taxpayer details for the merchant identified by merchantNumber.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"encryptedTin","in":"query","description":"Specifies whether to return the Taxpayer Identification Number (TIN) in encrypted format.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Returns a Taxpayer's details successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.TaxpayerV2"}}}},"204":{"description":"No content."},"400":{"description":"Bad Request: If merchant number is null or empty. Or URL refers to an obsolete version of API.","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: Taxpayer details 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.TaxpayerV2":{"required":["businessLegalName","tin","tinTypeID"],"type":"object","properties":{"legalFirstName":{"type":"string","description":"First name of the tax payer.","nullable":true},"legalLastName":{"type":"string","description":"Last name of the tax payer.","nullable":true},"tin":{"maxLength":9,"minLength":9,"type":"string","description":"Taxpayer Identification Number (TIN). Must be exactly 9 characters long."},"encryptedTIN":{"type":"string","description":"Encrypted representation of the TIN for security purposes.","format":"byte","nullable":true},"tinLastFour":{"type":"string","description":"Represents last fout digits of TIN number","nullable":true,"readOnly":true},"tinTypeID":{"maximum":3,"minimum":1,"type":"string","description":"Identifier for the type of TIN. Must be between 1 and 3."},"businessLegalName":{"minLength":1,"type":"string","description":"The legal name of the business associated with the taxpayer."},"stateIncorporatedCode":{"type":"string","description":"The state where the business is incorporated. Represented as a two-character code.","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}}}} ``` ## Update taxpayer details > Update the taxpayer details for the merchant identified by merchantNumber. ```json {"openapi":"3.0.1","info":{"title":"External US Onboarding Workflow","version":"0.0.1"},"paths":{"/api/demographics/v2/Taxpayers/{merchantNumber}":{"put":{"tags":["Tax Payer"],"summary":"Update taxpayer details","description":"Update the taxpayer details for the merchant identified by merchantNumber.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"encryptedTin","in":"query","description":"Specifies whether to return the Taxpayer Identification Number (TIN) in encrypted format.","schema":{"type":"boolean","default":false}}],"requestBody":{"description":"Taxpayer model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.TaxpayerV2"}}},"required":true},"responses":{"200":{"description":"Saves a Taxpayer successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDemographics.Api.Models.TaxpayerV2"}}}},"202":{"description":"Accepted: Request change was accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedChange.Client.Models.StagedChangeResponse"}}}},"400":{"description":"Bad Request: If merchant number is null or empty, or data is invalid. Or URL refers to an obsolete version of API.","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:: Resource not found exception.","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.TaxpayerV2":{"required":["businessLegalName","tin","tinTypeID"],"type":"object","properties":{"legalFirstName":{"type":"string","description":"First name of the tax payer.","nullable":true},"legalLastName":{"type":"string","description":"Last name of the tax payer.","nullable":true},"tin":{"maxLength":9,"minLength":9,"type":"string","description":"Taxpayer Identification Number (TIN). Must be exactly 9 characters long."},"encryptedTIN":{"type":"string","description":"Encrypted representation of the TIN for security purposes.","format":"byte","nullable":true},"tinLastFour":{"type":"string","description":"Represents last fout digits of TIN number","nullable":true,"readOnly":true},"tinTypeID":{"maximum":3,"minimum":1,"type":"string","description":"Identifier for the type of TIN. Must be between 1 and 3."},"businessLegalName":{"minLength":1,"type":"string","description":"The legal name of the business associated with the taxpayer."},"stateIncorporatedCode":{"type":"string","description":"The state where the business is incorporated. Represented as a two-character code.","nullable":true}},"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}}}} ``` --- # 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/tax-payer.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.