> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.middesk.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server. # TIN object > Lists the contents of a TIN record. This page describes what Middesk returns when you run a Taxpayer Identification Number (TIN) match request. **`Example JSON response`** ```json title="Example JSON response" { "object": "tin", "name": "Middesk, Inc.", "tin": "27-1883160", "verified": false, "verified_by": "business", "mismatch": false, "unknown": true, "issued": true, "error": null, "business_id": "32e7fb2c-60ca-4ddc-add2-694475b73f2b", "created_at": "2019-01-21T06:43:23.313Z", "updated_at": "2019-01-21T06:44:07.184Z" } ``` ## TIN attributes | Attribute | Type | Description | | ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string \| null | The legal entity name associated with that TIN. The name field is `null` by default when the Business and TIN objects are created, but filled once Middesk fulfills the report. | | `tin` | string | TIN provided during Business creation. | | `verified` | boolean \| null | Details on whether the TIN that was provided belongs to the entity name that was provided. The `verified` field is `null` by default when the Business and TIN object are created, but filled once Middesk fulfills the report. | | `verified_by` (optional) | string | If the TIN is verified using the business name, this field is populated with "business". If the TIN is verified using the person's name, this field populates with `person`. | | `issued` | boolean \| null | Details on whether the TIN is currently issued. If this cannot be determined, the value is `null`. | | `mismatch` | boolean | If the TIN is not verified against the submitted name, Middesk may return a recommended entity name which is flagged as a mismatch. | | `unknown` | boolean | If the TIN is not verified against the submitted name and no potential name is found, the TIN is flagged as unknown. | | `error` | string \| null | If there is an error on the TIN Matching request such as the IRS being unavailable, this field populates with the error string (example: `irs_unavailable`). | | `business_id` | string | The ID of the Business this TIN belongs to. | | `created_at` | timestamp | The timestamp when this TIN was created. | | `updated_at` | timestamp | The timestamp when this TIN last updated. | ## TIN review tasks To make decisioning easier off the above TIN data, key insights aggregate into review tasks on the Business payload (`business.review.review_tasks`). ### TIN Match This review task indicates if Middesk could verify the TIN and name match with the IRS. The following example indicates the possible states of this task. The TIN is only verified against the person name if that feature is enabled for your account. **`TIN Match found`** ```json title="TIN Match found" { "key": "tin", "category": "tin", "label": "TIN Match", "sub_label": "Found", "sub_key": "found", "status": "success", "message": "The IRS has a record for the submitted TIN and Business Name combination" } ``` ### TIN error When the TIN Match results in an error, an additional TIN error review task is available to allow for more granular actions depending on the type of error. **`IRS unavailable`** ```json title="IRS unavailable" { "key": "tin_error", "category": "tin", "label": "TIN Error", "sub_label": "IRS Unavailable", "sub_key": "irs_unavailable", "status": "failure", "message": "IRS Unavailable" } ``` ### TIN issued If the TIN fails to be verified against the Business name provided, the IRS indicates if the TIN has been issued or not. Newly issued TINs may take several days to several weeks to be processed into the IRS' database, so if this status is received from the IRS, it could be the case that the TIN is still being processed at the IRS. This review task is present if the IRS indicates that the TIN is not yet issued, otherwise, it won't be present in the review tasks list. **`TIN not issued`** ```json title="TIN not issued" { "key": "tin_issued", "category": "tin", "label": "TIN Match", "sub_label": "Not Issued", "sub_key": "not_issued", "status": "failure", "message": "TIN has not been issued by the IRS. There is often a delay after formation for the IRS database to process TINs for new businesses." } ``` ## Verify EINs and SSNs against individuals Some small businesses like single-member LLCs have EINs that match an officer's name instead of the registered business name. To use this feature, you must pass in both the EIN/TIN and the individual's name. If the TIN is verified using a person's name, a warning displays on the TIN match card in the Middesk Dashboard as a Person Match. ### EIN verification JSON response The Employer Identification Numbers (EIN) response includes `verified_by` as an optional field. If the TIN is verified using the business name, this field populates with `business`. If the TIN is verified using the person's name, this field populates with the "person." **`Verified response`** ```json title="Verified response" { "object": "tin", "name": "Middesk, Inc.", "tin": "27-5683160", "verified": true, "verified_by": "business", "mismatch": false, "unknown": false, "issued": null, "error": null, "business_id": "32e7fb2c-60ca-4ddc-add2-694475b73f2b", "created_at": "2019-01-21T06:43:23.313Z", "updated_at": "2019-01-21T06:44:07.184Z" } ``` ### Example review task JSON response If the EIN/TIN is verified using the person's name, the Review Task API (`business.review.review_tasks`) returns a response with a warning sublabel and the following message: "The IRS has a record for the submitted TIN and Person Name combination." ```json { "key": "unique identifier for the task", "category": "tin", "label": "TIN Match", "sub_label": "Warning", "status": "warning", "message": "The IRS has a record for the submitted TIN and Person Name combination" } ``` > **Get a demo** > > Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.