Assist_Design/freebit-api-docs/PA05-41_esim-account-activation.md

PA05-41 - eSIM Account Activation (eSIMアカウント開通)

Overview

Handles eSIM activation requests from OEM including new activations, MNP transfers, and reissues.

• Activation is asynchronous - not immediate; completion is notified via the "eSIM Request Completion Notification File"
• For file format details, refer to the "CSV File Format Definition (MVNO Edition)" sheet "eSIM依頼完了通知ファイル"
• When aladinOperated is "10" (operated) and addKind is not "N" (new), the API returns 400-356 (unsupported pattern)

---

Request

Method

POST (JSON format, URL-encoded)

URL

https://[host]/emptool/api/mvno/esim/addAcnt/

Authentication

Obtained via separate authentication API, included in request parameters.

POST Parameters

No	Parameter	Name	Required	Description
1	json	JSON Parameters	◎	Main request body

JSON Parameters

No	Parameter	Name	Level	Type	Min	Max	Required	Description
1	authKey	Authentication Key	1	Alphanumeric	-	-	◎	Obtained from OEM authentication
2	aladinOperated	ALADIN Operated Flag	1	Half-width numeric	2	2	-	"10": Operated, "20": Not operated. Defaults to "20" if omitted
3	masterAccount	Master Account	1	Alphanumeric + symbols	1	64	△	IIC master account. Not required if: not using User Management Service, no planCode specified, or addKind is "R"
4	masterPassword	Master Password	1	Alphanumeric + symbols	1	256	△	IIC master password. Required when createType is "new". Not required if: not using User Management Service, no planCode specified, or addKind is "R"
5	createType	Registration Type	1	Half-width alpha	3	3	△	"new": Create new master account, "add": Add service account to existing. "add" not allowed without User Management Service. Not required if: no planCode specified, or addKind is "R"
6	eid	eSIM Identifier	1	Half-width numeric	32	32	◎	Target SIM's eSIM identifier (EID)
7	account	Account	1	Half-width numeric	11	14	△	Target SIM's phone number. Not required when aladinOperated is "20" and addKind is "N". Required otherwise
8	simKind	SIM Type	1	Alphanumeric	2	2	△	"E2": No SMS, "E3": With SMS, "E0": With voice. Not required when addKind is "R". Required otherwise
9	contractLine	Contract Line Type	1	Alphanumeric	2	2	△	"4G": 4G line, "5G": 5G line. Not required when aladinOperated is "10" or addKind is "R". Defaults to "4G" if omitted
10	repAccount	Representative Number	1	Half-width numeric	11	14	△	Parent phone number. Required when aladinOperated is "10" and addKind is "N". Not required when addKind is "R". Otherwise required for specific representative number activation
11	addKind	Activation Type	1	Half-width alpha	1	1	◎	"N": New, "M": MNP transfer, "R": Reissue
12	reissue	Reissue Info	1	Object	-	-	△	Required when aladinOperated is "20" and addKind is "R". Not required otherwise
13	reissue.oldProductNumber	Old Product Number	2	Alphanumeric	15	15	△	Product number of the SIM before reissue. First 2 chars uppercase alpha, remaining 13 digits (e.g., AXxxxxxxxxxxxxx). Only for physical SIM → eSIM
14	reissue.oldEid	Old eSIM Identifier	2	Half-width numeric	32	32	△	EID of the eSIM before reissue. Only for eSIM → eSIM
15	mnp	MNP Info	1	Object	-	-	△	Required when aladinOperated is "20" and addKind is "M". Not required otherwise
16	mnp.reserveNumber	MNP Reservation Number	2	Half-width numeric	10	10	○	MNP reservation number (no hyphens)
17	mnp.lastnameKanji	Last Name (Kanji)	2	Full-width characters	1	50	○	UTF-8 range. For non-corporate: lastname + full-width space + firstname ≤ 50 chars. For corporate (gender "C"): lastname ≤ 50 chars. See Character Rules
18	mnp.firstnameKanji	First Name (Kanji)	2	Full-width characters	*	*	△	Required when gender is not "C" (corporate). See lastname for length rules
19	mnp.lastnameZenKana	Last Name (Full Katakana)	2	Full-width katakana	1	50	○	UTF-8 range. For non-corporate: lastname + full-width space + firstname ≤ 50 chars. For corporate (gender "C"): lastname ≤ 50 chars. See Character Rules
20	mnp.firstnameZenKana	First Name (Full Katakana)	2	Full-width katakana	*	*	△	Required when gender is not "C" (corporate). See lastname for length rules
21	mnp.gender	Gender	2	Half-width alpha	1	1	○	"M": Male, "W": Female, "C": Corporate
22	mnp.birthday	Date of Birth	2	Half-width numeric	8	8	△	YYYYMMDD format. Required when gender is not "C" (corporate)
23	shipDate	Ship Date	1	Half-width numeric	8	8	△	YYYYMMDD format. Past dates OK, future dates NG. Required when aladinOperated is "10"
24	planCode	Plan Code	1	Alphanumeric + symbols	1	32	-	Plan to apply. No plan = no connectivity. Not required when addKind is "R"
25	deliveryCode	Delivery Code	1	Alphanumeric	1	10	-	Arbitrary code set by each OEM

Legend: ◎ Required | ○ Required within level | △ Conditional

---

Character Rules

Kanji Fields

• Allowed: Characters within UTF-8 range that can be converted to Windows-31J, excluding:
  • Half-width space (U+0020)
  • Half-width alphanumeric (U+0021–U+007E)
  • Half-width katakana (U+FF61–U+FF9F)
• Full-width spaces: Allowed within string for corporate ("C") only; never allowed at string edges

Katakana Fields

• Allowed Unicode ranges only:
  • Full-width space: U+3000
  • Full-width digits: U+FF10–U+FF19
  • Full-width uppercase alpha: U+FF21–U+FF3A
  • Full-width katakana: U+30A1–U+30EF, U+30F3 (ン), U+30F4 (ヴ), U+30FC (ー)
• Full-width spaces: Allowed within string for corporate ("C") only; never allowed at string edges

---

Request Examples

New Activation (ALADIN not operated, no User Management Service, with plan, no representative number)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "simKind": "E2",
  "contractLine": "4G",
  "addKind": "N",
  "planCode": "100K_PLAN",
  "deliveryCode": "XXXX"
}

New Activation (ALADIN not operated, no User Management Service, no plan, with representative number)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "eid": "11112222333344445555666677778888",
  "simKind": "E0",
  "repAccount": "08000001111",
  "addKind": "N",
  "deliveryCode": "XXXX"
}

MNP Transfer (ALADIN operated, with User Management Service, no representative number)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "aladinOperated": "10",
  "masterAccount": "testAccount@test.ne.jp",
  "masterPassword": "testPass",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "account": "08011112222",
  "simKind": "E0",
  "contractLine": "4G",
  "addKind": "M",
  "shipDate": "20170301",
  "planCode": "100K_PLAN",
  "deliveryCode": "XXXX"
}

MNP Transfer (ALADIN operated, no User Management Service, with representative number)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "aladinOperated": "10",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "account": "08011112223",
  "simKind": "E3",
  "repAccount": "08000001111",
  "addKind": "M",
  "shipDate": "20170301",
  "planCode": "100K_PLAN"
}

MNP Transfer (ALADIN not operated, with User Management Service, individual)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "masterAccount": "testAccount@test.ne.jp",
  "masterPassword": "testPass",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "account": "08011112222",
  "simKind": "E0",
  "contractLine": "5G",
  "addKind": "M",
  "mnp": {
    "reserveNumber": "1101201234",
    "lastnameKanji": "山田",
    "firstnameKanji": "太郎",
    "lastnameZenKana": "ヤマダ",
    "firstnameZenKana": "タロウ",
    "gender": "M",
    "birthday": "19900101"
  },
  "planCode": "100K_PLAN",
  "deliveryCode": "XXXX"
}

MNP Transfer (ALADIN not operated, no User Management Service, corporate, with representative number)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "createType": "new",
  "eid": "11112222333344445555666677778888",
  "account": "08011112223",
  "simKind": "E0",
  "repAccount": "08000001111",
  "addKind": "M",
  "mnp": {
    "reserveNumber": "1101201235",
    "lastnameKanji": "フリービット　株式会社",
    "lastnameZenKana": "フリービット　カブシキカイシャ",
    "gender": "C"
  },
  "planCode": "100K_PLAN"
}

Reissue (ALADIN not operated, physical SIM → eSIM)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account": "08011112225",
  "eid": "11112222333344445555666677778888",
  "addKind": "R",
  "reissue": {
    "oldProductNumber": "CD0009999999004"
  }
}

---

Response

Format

JSON

Parameters

No	Parameter	Name	Level	Type	Description
1	resultCode	Result Code	1	Numeric	Processing result code
2	status	Status	1	Object	Status details
3	status.message	Message	2	Alphanumeric + symbols	Processing result message
4	status.statusCode	Detail Result Code	2	Numeric	Detailed status code

---

Response Codes

Status	Status Code	Detail Code	Message	Description
○	200	100	OK	Success
×	400	201	Bad Request	Parameter error - account (masterAccount/account) issue
×	400	202	Bad Request	Parameter error - master password issue
×	400	204	Bad Request	Parameter error - other parameter issue
×	400	215	Bad Request	Parameter error - plan code issue
×	400	228	Bad Request	Parameter error - authentication key (authKey) issue
×	400	253	Bad Request	Parameter error - last name (kanji) issue
×	400	254	Bad Request	Parameter error - first name (kanji) issue
×	400	255	Bad Request	Parameter error - last name (full katakana) issue
×	400	256	Bad Request	Parameter error - first name (full katakana) issue
×	400	257	Bad Request	Parameter error - gender issue
×	400	258	Bad Request	Parameter error - date of birth issue
×	400	266	Bad Request	Parameter error - product number (productNumber/oldProductNumber) issue
×	400	269	Bad Request	Parameter error - representative number issue
×	400	274	Bad Request	Parameter error - delivery code issue
×	400	276	Bad Request	Parameter error - ship date issue
×	400	277	Bad Request	Parameter error - SIM type issue
×	400	278	Bad Request	Parameter error - ALADIN operated flag issue
×	400	279	Bad Request	Parameter error - registration type issue
×	400	307	Bad Request	Parameter error - MNP reservation number issue
×	400	333	Bad Request	Parameter error - activation type issue
×	400	356	Bad Request	Parameter error - unsupported pattern (ALADIN operated flag + activation type)
×	400	360	Bad Request	Parameter error - contract type issue
×	400	370	Bad Request	Parameter error - eSIM identifier (eid/oldEid) issue
×	403	205	Auth Error	Authentication key problem
×	404	232	Not Found	Specified plan does not exist
×	500	208	NG	Account (masterAccount/account) duplicate error
×	500	210	NG	Account (masterAccount/account) not found error
×	500	230	NG	Account is waiting for async processing; request not allowed
×	500	275	NG	No available phone number inventory for the specified representative number
×	500	284	NG	Representative number is locked
×	500	287	NG	Representative number does not exist or is unavailable
×	500	288	NG	Product number is unavailable (does not exist or already in use)
×	500	289	NG	SIM type does not match representative number's type
×	500	304	NG	SIM type does not match representative number's type
×	500	310	NG	MNP reservation number has duplication or other issues
×	500	371	NG	eSIM identifier (eid) duplicate error
×	500	372	NG	eSIM identifier (eid) not found error
×	500	374	NG	Specified eSIM identifier has reached the monthly activation limit
×	500	900	NG	Unexpected error occurred

---

Response Example

{
  "resultCode": 100,
  "status": {
    "message": "OK",
    "statusCode": 200
  }
}