# Tax Payer

## Get Taxpayer Details (v2.0)

> 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 (v2.0)","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 (v2.0)

> 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 (v2.0)","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}}}}
```