Guides

Old - Hosted Flow

Suggest Edits

The following is a guide to send your users through the Middesk tax registration hosted flow. The hosted flow is used to setup state tax accounts on behalf of your users.

Create an OAuth client

The first step in integrating with the tax registration hosted flow is to create an OAuth client in the Middesk developer settings dashboard.

Once you have obtained both the client_id and client_secret you're ready to start building the integration.

Obtain an OAuth access token

You will need to generate an OAuth access token to make requests on behalf of your users.

📘

Getting started with OAuth

See our OAuth Reference for instructions on generating an OAuth access token.

Does your access token have the correct permissions?

Make sure you request the read_write OAuth scope.

Create a company resource and prefill information

Creating an agent company is required before sending your users through the tax registration hosted flow. The company holds important details required to setup its state tax accounts. All fields are optional, but anything provided at the time of creation will be used to prefill the corresponding fields in the hosted flow.

Use the OAuth access token retrieved above to create a company on behalf of another Middesk account. See Gaining Access if you're having trouble making API requests with the OAuth access token.

View the Create a Company endpoint in the API reference for a list of all possible company attributes.

curl http://api.middesk.com/v1/agent/companies \
  -X POST \
  -H 'Authorization: Bearer 08ea6a9ec1d4097f6c569499' \
  -H 'Content-Type: application/json' \
  --data '{
    "formation_state": "DE",
    "legal_name": "Middesk",
    "ein": "123456789",
    "contact_email": "[email protected]",
    "contact_name": "John Smith",
    "contact_phone_number": "(555) 555-5555",
    "dba_name": "Deskmid",
    "entity_type": "corporation",
    "formation_date": "2019-05-21",
    "industry": "Mushroom Production",
    "purpose": "A Purpose",
    "naics_code": 111411,
    "acquired": false,
    "legal_entity_changed": false,
    "fiscal_year_end": "2019-12-31",
    "addresses": [
      {
        "address_line1": "577 Howard St",
        "address_line2": null,
        "city": "San Francisco",
        "postal_code": "94105-4635",
        "state": "CA",
        "address_type": "primary"
      }
    ],
    "individuals": [
      {
        "address": {
          "address_line1": "577 Howard St.",
          "address_line2": null,
          "city": "San Francisco",
          "postal_code": "94105",
          "state": "CA"
        },
        "name": "Jane Smith",
        "titles": [
          "President"
        ],
        "signatory": true,
        "ownership_percentage": 0.1,
        "ssn": "000-00-0000",
        "dob": "1990-01-01"
      }
    ]
}'

After creating a company, you will receive a response from our API to confirm the creation of that company. Be sure to save a reference to the company id returned in the response.

{
  "object": "agent_company",
  "id": "e75a25f8-ef2a-42af-b25f-4c4a80b3c38f",
  "formation_state": "DE",
  "legal_name": "Middesk",
  "ein": "123456789",
  "contact_email": "[email protected]",
  "contact_name": "John Smith",
  "contact_phone_number": "(555) 555-5555",
  "dba_name": "Deskmid",
  "entity_type": "corporation",
  "formation_date": "2019-05-21",
  "industry": "Mushroom Production",
  "purpose": "A Purpose",
  "naics_code": 111411,
  "acquired": false,
  "legal_entity_changed": false,
  "fiscal_year_end": "2019-12-31",
  "addresses": [
    {
      "address_line1": "577 Howard St",
      "address_line2": null,
      "city": "San Francisco",
      "postal_code": "94105-4635",
      "state": "CA",
      "address_type": "primary"
    }
  ],
  "individuals": [
    {
      "address": {
        "address_line1": "577 Howard St.",
        "address_line2": null,
        "city": "San Francisco",
        "postal_code": "94105",
        "state": "CA"
      },
      "name": "Jane Smith",
      "titles": [
        "President"
      ],
      "signatory": true,
      "ownership_percentage": 0.1,
      "ssn": "000-00-0000",
      "dob": "1990-01-01"
    }
  ]
}

Generate a hosted flow link

Once you have created a company, you are ready to start generating links to the hosted flow for your users. Send the following request using a Middesk agent company_id. Attributes of the created company will be used to prefill the corresponding fields in the hosted flow.

View the Generating a Link endpoint in the API reference for a list of possible fields.

curl https://api.middesk.com/v1/agent/link \
  -X POST \
  -H "Authorization: Bearer 08ea6a9ec1d4097f6c569499" \
  -H "Content-Type: application/json" \
  --data '{
    "redirect_uri": "https://example.redirect.com",
    "company_id": "60688c40-73fe-0139-094f-342e993324d0",
    "tax_registrations": [
      { "state": "CA" }
    ]
  }'

The request returns a response with a link to the hosted flow

{
  "link": "https://agent.middesk.com/applications/0400f67a-be6b-486f-95d5-acace80aa28f"
}

Redirecting your user to the link

The response to your link generation request includes a link. Redirect to this link to send your user into the hosted flow. The link is valid until the user completes the application. You can generate another if you wish to have the user complete the hosted flow for a different set of states.

1650

Redirecting your user back to your platform

The hosted flow requires that you pass a redirect_uri when creating a link. Middesk issues a redirect to this URL when the user completes the tax registration hosted flow. This means that they have successfully kicked off the process to setup their state tax accounts.

You can view the status of the created tax registrations by:

Using webhooks to receive updates

OAuth client webhooks allow you to receive webhooks for other Middesk accounts that have given you account authorization by completing the OAuth authorization flow.

📘

OAuth client webhooks

You can start receiving webhook events for your user's tax registrations after you have added a webhook URL to your OAuth client. Visit the Middesk Developer Dashboard to create a webhook url for your OAuth Client.

Visit our guide for using webhooks for detailed constructions on consuming webhook events.

There are two type of tax registration events:

  • agent_tax_registration.created
  • agent_tax_registration.updated

Below is an example agent_tax_registration.updated webhook event. The company_id field can be used to associate the tax registration with the company initially created.

{
  "object": "event",
  "id": "f215a707-655e-400f-84e6-fbb949f5612a",
  "account_id": "7f1b5df0-7f95-0139-fe19-6677fd0cda41",
  "type": "agent_tax_registration.updated",
  "data": {
    "object": {
      "object": "agent_tax_registration",
      "id": "60688c40-73fe-0139-094f-342e993324d0",
      "company_id": "60688c40-73fe-0139-094f-342e993324d0",
      "status": "pending",
      "state": "NJ",
      "formation_state": "DE",
      "legal_name": "Middesk",
      "previous_legal_name": null,
      "ein": "12-3456789",
      "contact_email": "[email protected]",
      "contact_name": "John Smith",
      "contact_phone_number": "(555) 555-5555",
      "dba_name": "Deskmid",
      "ein": "12-3123123",
      "entity_type": "corporation",
      "formation_date": "2019-05-21",
      "industry": "Mushroom Production",
      "purpose": "A Purpose",
      "acquired": false,
      "acquisition_date": null,
      "legal_entity_changed": false,
      "fiscal_year_end": 2020,
      "addresses": [
        {
          "address_line1": "577 Howard St",
          "address_line2": null,
          "city": "San Francisco",
          "postal_code": "94105-4635",
          "state": "CA",
          "address_type": "primary"
        }
      ],
      "individuals": [
        {
          "address": {
            "address_line1": "570 Glenridge St.",
            "address_line2": null,
            "city": "Sewaren",
            "postal_code": "07077",
            "state": "NJ"
          },
          "name": "Jane Smith",
          "titles": [
            "President"
          ],
          "signatory": true,
          "ownership_percentage": 0.1,
          "ssn": "000-00-0000",
          "dob": "1990-01-01"
        }
      ],
      "items": [
        {
          "id": "01f2f2c0-73fc-0139-094f-342e993324d0",
          "agency": "Division of Revenue and Enterprise Services",
          "label": "Employer Registration Number",
          "value": null,
          "status": "open"
        },
        {
          "id": "1752add0-73fc-0139-094f-342e993324d0",
          "agency": "Department of Labor and Workforce Development",
          "label": "Unemployment Experience Rate",
          "value": null,
          "status": "open"
        },
        {
          "id": "c6ca0630-74b1-0139-7bb1-342e993324d0",
          "agency": "Department of Labor and Workforce Development",
          "label": "Disability Insurance Rate",
          "value": null,
          "status": "open"
        }
      ],
      "tax_accounts": [
        {
          "agency": "Division of Revenue and Enterprise Services",
          "username": "middeskagain",
          "email": "[email protected]",
          "password": "allbusiness123"
        }
      ]
    }
  }
}

Updated 5 months ago