Change agent

Last updated Jun 14, 2026

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

providerstringRequired

One of"matter""external"

external_provider_namestringOptional

addressobjectOptional

Structured address.

line1stringRequired

line2stringOptional

citystringRequired

countystringOptional

County, parish, or borough. Optional for most addresses but required in the registered-agent block of certain state filings (DE Certificate of Incorporation per 8 Del. C. §131; analogous fields in NY and MD, parishes in LA). When omitted, the recommendation engine derives the county from line1 + region against the @repo/jurisdictions data — populated automatically for Matter-provided registered agents.

regionstringRequired

State, province, or region code (e.g. DE, CA, NY).

postal_codestringRequired

countrystringRequired

ISO 3166-1 alpha-2.

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/entities/{id}/registered_agent" \  -H "Content-Type: application/json" \  -d '{    "provider": "matter",    "external_provider_name": "string",    "address": {      "line1": "548 Market St",      "city": "San Francisco",      "region": "CA",      "postal_code": "94104",      "country": "US"    }  }'

const body = JSON.stringify({  "provider": "matter",  "external_provider_name": "string",  "address": {    "line1": "548 Market St",    "city": "San Francisco",    "region": "CA",    "postal_code": "94104",    "country": "US"  }})fetch("https://api.mattermode.com/v1/entities/{id}/registered_agent", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/entities/{id}/registered_agent"  body := strings.NewReader(`{    "provider": "matter",    "external_provider_name": "string",    "address": {      "line1": "548 Market St",      "city": "San Francisco",      "region": "CA",      "postal_code": "94104",      "country": "US"    }  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

import requestsheaders = {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = {    "provider": "matter",    "external_provider_name": "string",    "address": {        "line1": "548 Market St",        "city": "San Francisco",        "region": "CA",        "postal_code": "94104",        "country": "US"    }}resp = requests.post(    "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/registered_agent",    headers=headers,    json=payload,)resp.raise_for_status()print(resp.json())

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{  "provider": "matter",  "external_provider_name": "string",  "address": {    "line1": "548 Market St",    "city": "San Francisco",    "region": "CA",    "postal_code": "94104",    "country": "US"  }}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/entities/{id}/registered_agent"))  .header("Content-Type", "application/json")  .POST(body)  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}

using System;using System.Net.Http;using System.Text;var body = new StringContent("""{  "provider": "matter",  "external_provider_name": "string",  "address": {    "line1": "548 Market St",    "city": "San Francisco",    "region": "CA",    "postal_code": "94104",    "country": "US"  }}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/entities/{id}/registered_agent", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/registered_agent' \  --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \  --header 'Matter-Version: 2026-06-10' \  --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \  --header 'Content-Type: application/json' \  --data '{  "provider": "matter",  "external_provider_name": "string",  "address": {    "line1": "548 Market St",    "city": "San Francisco",    "region": "CA",    "postal_code": "94104",    "country": "US"  }}'

const response = await fetch("https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/registered_agent", {  method: "POST",  headers: {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",    "Content-Type": "application/json",  },  body: JSON.stringify({    "provider": "matter",    "external_provider_name": "string",    "address": {      "line1": "548 Market St",      "city": "San Francisco",      "region": "CA",      "postal_code": "94104",      "country": "US"    }  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "registered_agent": {
    "id": "string",
    "object": "registered_agent",
    "entity_id": "ent_Nq3KcAbc",
    "jurisdiction": "US-DE",
    "provider": "matter",
    "address": {
      "line1": "548 Market St",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94104",
      "country": "US"
    },
    "effective_date": "2026-04-25",
    "created": 1745539200,
    "updated": 1745539200,
    "livemode": false
  },
  "filing": {
    "id": "string",
    "object": "filing",
    "entity_id": "ent_Nq3KcAbc",
    "type": "certificate_of_amendment",
    "jurisdiction": "US-DE",
    "status": "preparing",
    "created": 1745539200,
    "updated": 1745539200,
    "livemode": false
  }
}

{
  "type": "https://mattermode.com/docs/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Request body could not be parsed as JSON.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_request",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "code": "authentication_required",
  "detail": "No bearer token was supplied. Pass `Authorization: Bearer sk_live_...` on every request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#authentication_required",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "Request rate exceeded for this key. Retry after `retry_after` seconds or honor the `Retry-After` header.",
  "doc_url": "https://mattermode.com/docs/guides/errors#rate_limit_exceeded",
  "request_id": "req_Qw9xYz8A",
  "retry_after": 30
}

Change the registered agent.

Replace the entity's registered agent in its state of incorporation (or in any qualified jurisdiction) with a new one. Generates and files the state-specific change-of-agent form, updates the agent address on file with the secretary of state, and re-points service-of-process delivery for inbound mail.

Provider modes (provider) - matter — Matter assumes the registered-agent role itself. Default, no per-state setup; service-of-process is digitized via the mail API on receipt. - external — supply an external_provider_name and address to point service-of-process at a third-party agent (CT Corp, Cogency Global, in-house counsel, etc.). The change is filed with the state but Matter does not relay mail.

Common reasons to call this: switching from an external agent at formation to Matter as agent, satisfying an investor or counsel preference for a specific external agent, or correcting an out-of-date address on a previously qualified state.

Returns 202 Accepted. On completion, emits one of: entity.state_changed, filing.accepted. Subscribe via `POST /v1/webhook_endpoints` to consume. Idempotent via Idempotency-Key. See idempotency.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

providerstringRequired

One of"matter""external"

external_provider_namestringOptional

addressobjectOptional

Structured address.

line1stringRequired

line2stringOptional

citystringRequired

countystringOptional

regionstringRequired

State, province, or region code (e.g. DE, CA, NY).

postal_codestringRequired

countrystringRequired

ISO 3166-1 alpha-2.

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/entities/{id}/registered_agent" \  -H "Content-Type: application/json" \  -d '{    "provider": "matter",    "external_provider_name": "string",    "address": {      "line1": "548 Market St",      "city": "San Francisco",      "region": "CA",      "postal_code": "94104",      "country": "US"    }  }'

const body = JSON.stringify({  "provider": "matter",  "external_provider_name": "string",  "address": {    "line1": "548 Market St",    "city": "San Francisco",    "region": "CA",    "postal_code": "94104",    "country": "US"  }})fetch("https://api.mattermode.com/v1/entities/{id}/registered_agent", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/entities/{id}/registered_agent"  body := strings.NewReader(`{    "provider": "matter",    "external_provider_name": "string",    "address": {      "line1": "548 Market St",      "city": "San Francisco",      "region": "CA",      "postal_code": "94104",      "country": "US"    }  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

import requestsheaders = {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = {    "provider": "matter",    "external_provider_name": "string",    "address": {        "line1": "548 Market St",        "city": "San Francisco",        "region": "CA",        "postal_code": "94104",        "country": "US"    }}resp = requests.post(    "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/registered_agent",    headers=headers,    json=payload,)resp.raise_for_status()print(resp.json())

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{  "provider": "matter",  "external_provider_name": "string",  "address": {    "line1": "548 Market St",    "city": "San Francisco",    "region": "CA",    "postal_code": "94104",    "country": "US"  }}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/entities/{id}/registered_agent"))  .header("Content-Type", "application/json")  .POST(body)  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}

using System;using System.Net.Http;using System.Text;var body = new StringContent("""{  "provider": "matter",  "external_provider_name": "string",  "address": {    "line1": "548 Market St",    "city": "San Francisco",    "region": "CA",    "postal_code": "94104",    "country": "US"  }}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/entities/{id}/registered_agent", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/registered_agent' \  --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \  --header 'Matter-Version: 2026-06-10' \  --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \  --header 'Content-Type: application/json' \  --data '{  "provider": "matter",  "external_provider_name": "string",  "address": {    "line1": "548 Market St",    "city": "San Francisco",    "region": "CA",    "postal_code": "94104",    "country": "US"  }}'

const response = await fetch("https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/registered_agent", {  method: "POST",  headers: {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",    "Content-Type": "application/json",  },  body: JSON.stringify({    "provider": "matter",    "external_provider_name": "string",    "address": {      "line1": "548 Market St",      "city": "San Francisco",      "region": "CA",      "postal_code": "94104",      "country": "US"    }  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "registered_agent": {
    "id": "string",
    "object": "registered_agent",
    "entity_id": "ent_Nq3KcAbc",
    "jurisdiction": "US-DE",
    "provider": "matter",
    "address": {
      "line1": "548 Market St",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94104",
      "country": "US"
    },
    "effective_date": "2026-04-25",
    "created": 1745539200,
    "updated": 1745539200,
    "livemode": false
  },
  "filing": {
    "id": "string",
    "object": "filing",
    "entity_id": "ent_Nq3KcAbc",
    "type": "certificate_of_amendment",
    "jurisdiction": "US-DE",
    "status": "preparing",
    "created": 1745539200,
    "updated": 1745539200,
    "livemode": false
  }
}

{
  "type": "https://mattermode.com/docs/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Request body could not be parsed as JSON.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_request",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "code": "authentication_required",
  "detail": "No bearer token was supplied. Pass `Authorization: Bearer sk_live_...` on every request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#authentication_required",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "Request rate exceeded for this key. Retry after `retry_after` seconds or honor the `Retry-After` header.",
  "doc_url": "https://mattermode.com/docs/guides/errors#rate_limit_exceeded",
  "request_id": "req_Qw9xYz8A",
  "retry_after": 30
}

Change the registered agent.

Request Body

Response Body

202application/json

400application/problem+json

401application/problem+json

429application/problem+json

Change the registered agent.

Request Body

Response Body

202application/json

400application/problem+json

401application/problem+json

429application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`