Assist_Design/freebit-api-docs/PA05-33_ota-account-activation.md

PA05-33 - OTA Account Activation (OTAアカウント開通)

Overview

Activates a pre-created OTA-SIM based on an OEM request. Supports new activations, MNP transfers, and reissues.

• Activation is asynchronous — not immediate. Completion is notified via file output:
  • Activation Ready Notification File — output when activation preparation is complete
  • Activation Complete Notification File — output when activation is fully complete
  • File specifications: see CSV File Format Definition (MVNO Edition)
• When aladinOperated is "10" (operated) and addKind is "R" (reissue), the API returns 400-356 (unsupported pattern). Reissue with ALADIN operated is handled via file integration instead.

---

Request

Method

POST (JSON format, URL-encoded)

URL

https://[host]/emptool/api/mvno/ota/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" (reissue)
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, or addKind "R"
5	createType	Registration Type	1	Half-width alpha	3	3	△	"new": Create new master account, "add": Add to existing. "add" not allowed without User Management Service. Not required for "R"
6	account	Account	1	Half-width numeric	11	14	◎	Target SIM phone number. If activating with same number as tempAccount, specify the tempAccount value
7	tempAccount	Temporary Account	1	Half-width numeric	11	14	◎	OTA-SIM temporary phone number
8	productNumber	Product Number	1	Alphanumeric	15	15	◎	Product number on back of OTA-SIM. First 2 chars uppercase alpha, remaining 13 digits (e.g., AXxxxxxxxxxxxxx)
9	repAccount	Representative Number	1	Half-width numeric	11	14	△	Parent phone number. Required unless addKind is "R" (reissue)
10	size	SIM Size	1	Half-width alpha	4	8	◎	"standard", "nano", or "micro"
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 addKind is "R". Not required otherwise
13	reissue.oldSize	Original SIM Size	2	Half-width alpha	4	8	○	SIM size before reissue: "standard", "nano", or "micro"
14	reissue.oldProductNumber	Original Product Number	2	Alphanumeric	15	15	○	Product number of the SIM before reissue
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.reserveExpireDate	MNP Reservation Expiry	2	Half-width numeric	8	8	○	YYYYMMDD format. Future dates only
18	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
19	mnp.firstnameKanji	First Name (Kanji)	2	Full-width characters	*	*	△	Required when gender is not "C" (corporate). See lastname for length rules
20	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
21	mnp.firstnameZenKana	First Name (Full Katakana)	2	Full-width katakana	*	*	△	Required when gender is not "C" (corporate). See lastname for length rules
22	mnp.gender	Gender	2	Half-width alpha	1	1	○	"M": Male, "W": Female, "C": Corporate
23	mnp.birthday	Date of Birth	2	Half-width numeric	8	8	△	YYYYMMDD format. Required when gender is not "C" (corporate)
24	shipDate	Ship Date	1	Half-width numeric	8	8	△	YYYYMMDD format. Past dates OK, future dates NG. Required when aladinOperated is "10". When "10" + addKind "R", treated as reissue completion date
25	planCode	Plan Code	1	Alphanumeric + symbols	1	32	-	Plan to apply. No plan = no connectivity. Not required for addKind "R"
26	globalIp	Global IP (yes/no)	1	Half-width numeric	2	2	-	"20": Disabled. If not specified, not processed. "10" (enabled) is deprecated. Not required for addKind "R"
27	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:

• Must be within UTF-8 range and convertible to Windows-31J encoding
• Excluded: half-width space (0x0020), half-width alphanumeric (0x0021-0x007E), half-width katakana (0xFF61-0xFF9F)
• Corporate ("C"): full-width spaces allowed
• Non-corporate: full-width spaces not allowed
• Full-width spaces not allowed at start/end of string

Katakana Fields

Allowed characters (Unicode ranges):

• Full-width space: 0x3000
• Full-width digits: 0xFF10-0xFF19
• Full-width uppercase alpha: 0xFF21-0xFF3A
• Full-width katakana: 0x30A1-0x30EF, 0x30F3 (ン), 0x30F4 (ヴ), 0x30FC (ー)
• Same corporate/non-corporate space rules as kanji fields

---

Request Examples

MNP Transfer (ALADIN operated, with User Management Service)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "aladinOperated": "10",
  "masterAccount": "testAccount@test.ne.jp",
  "masterPassword": "testPass",
  "createType": "new",
  "account": "08011112222",
  "tempAccount": "08022223333",
  "productNumber": "ZZ0009999999001",
  "repAccount": "08000001111",
  "size": "standard",
  "addKind": "M",
  "shipDate": "20170301",
  "planCode": "100K_PLAN",
  "globalIp": "20",
  "deliveryCode": "XXXX"
}

MNP Transfer (ALADIN operated, no User Management Service)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "aladinOperated": "10",
  "createType": "new",
  "account": "08011112223",
  "tempAccount": "08022223334",
  "productNumber": "ZZ0009999999002",
  "repAccount": "08000001111",
  "size": "nano",
  "addKind": "M",
  "shipDate": "20170301",
  "planCode": "100K_PLAN",
  "globalIp": "20"
}

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

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "masterAccount": "testAccount@test.ne.jp",
  "masterPassword": "testPass",
  "createType": "new",
  "account": "08011112222",
  "tempAccount": "08022223333",
  "productNumber": "ZZ0009999999001",
  "repAccount": "08000001111",
  "size": "nano",
  "addKind": "M",
  "mnp": {
    "reserveNumber": "1101201234",
    "reserveExpireDate": "20170323",
    "lastnameKanji": "山田",
    "firstnameKanji": "太郎",
    "lastnameZenKana": "ヤマダ",
    "firstnameZenKana": "タロウ",
    "gender": "M",
    "birthday": "19900101"
  },
  "planCode": "100K_PLAN",
  "globalIp": "20",
  "deliveryCode": "XXXX"
}

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

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "createType": "new",
  "account": "08011112223",
  "tempAccount": "08022223334",
  "productNumber": "ZZ0009999999002",
  "repAccount": "08000001111",
  "size": "micro",
  "addKind": "M",
  "mnp": {
    "reserveNumber": "1101201235",
    "reserveExpireDate": "20170323",
    "lastnameKanji": "フリービット　株式会社",
    "lastnameZenKana": "フリービット　カブシキカイシャ",
    "gender": "C"
  },
  "planCode": "100K_PLAN",
  "globalIp": "20"
}

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

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "createType": "new",
  "account": "08011112224",
  "tempAccount": "08011112224",
  "productNumber": "ZZ0009999999003",
  "repAccount": "08000001111",
  "size": "nano",
  "addKind": "N",
  "planCode": "100K_PLAN",
  "deliveryCode": "XXXX"
}

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

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account": "08011112224",
  "tempAccount": "08011112224",
  "productNumber": "ZZ0009999999003",
  "repAccount": "08000001111",
  "size": "nano",
  "addKind": "N",
  "deliveryCode": "XXXX"
}

Reissue (ALADIN not operated)

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account": "08011112225",
  "tempAccount": "08022223336",
  "productNumber": "ZZ0009999999004",
  "size": "nano",
  "addKind": "R",
  "reissue": {
    "oldSize": "micro",
    "oldProductNumber": "CD0009999999004"
  },
  "globalIp": "20"
}

---

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/tempAccount) 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 issue
×	400	231	Bad Request	Parameter error - global IP 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	267	Bad Request	Parameter error - SIM size (size/oldSize) 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	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	308	Bad Request	Parameter error - MNP reservation expiry date issue
×	400	333	Bad Request	Parameter error - activation type issue
×	400	356	Bad Request	Parameter error - unsupported pattern (ALADIN operated flag + activation type)
×	403	205	Auth Error	Authentication key problem
×	404	232	Not Found	Specified plan does not exist
×	500	208	NG	Account (masterAccount/account/tempAccount) 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, already in use, etc.)
×	500	310	NG	MNP reservation number has duplication or other issues
×	500	334	NG	Temporary phone number does not match product number
×	500	342	NG	SIM size mismatch (does not match managed SIM size)
×	500	900	NG	Unexpected error occurred

---

Response Example

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

---

Related APIs

API	Name	Relationship
PA05-41	eSIM Account Activation	Similar API for eSIM activations (also supports MNP and reissue)
PA05-18	MVNO Semi-Black Account Temporary Registration	Pre-staging API for semi-black SIM MNP (queue-based)
PA05-19	MVNO Semi-Black Account Registration	Synchronous activation for semi-black SIMs